# kubectl patch: Usage, Options & Common CI Errors

> kubectl patch applies strategic-merge, JSON-merge, or JSON-patch updates. Patch types compared, scripting patches in CI, and the immutable-field error.

Source: https://latchkey.dev/learn/command-reference/kubectl-patch  
Updated: 2026-06-25

Surgically update one field from a script - pick the right patch type.

kubectl patch applies a partial update to a resource and is the scriptable alternative to edit. Choosing the correct --type (strategic, merge, or json) is what makes it work the way you expect.

## What it does

kubectl patch RESOURCE NAME -p '<patch>' merges a fragment into the live object. --type=strategic (the default) understands Kubernetes list-merge semantics; --type=merge is a plain RFC 7386 JSON merge that replaces lists wholesale; --type=json applies an RFC 6902 operation list (add/replace/remove at explicit paths). Pick by whether you need list-aware merging or precise path edits.

## Common usage

```Terminal
kubectl patch deploy/web -p '{"spec":{"replicas":3}}'
kubectl patch deploy/web --type=json \
  -p '[{"op":"replace","path":"/spec/replicas","value":3}]'
kubectl patch svc/web --type=merge -p '{"spec":{"type":"LoadBalancer"}}'
```

## Common errors in CI

The most common mistake is the wrong --type: a strategic-merge patch on a custom resource (which has no merge metadata) silently misbehaves - use --type=merge or --type=json for CRDs. "The order in patch list ... doesn't match" or a list being replaced instead of merged means you needed strategic but used merge. A JSON-patch "op" against a path that does not exist fails with "the server rejected our request"; add the parent first or use add. And patching an immutable field returns "field is immutable" - the field cannot change in place at all.

## Using this in CI

A runner has no kubeconfig, no cached context, and no interactive auth. Every kubectl invocation in CI needs the context supplied explicitly, and most confusing CI failures here are the command running against the wrong cluster or no cluster at all.

```Terminal
# never rely on the ambient context on a runner
kubectl --context "$KUBE_CONTEXT" -n "$NAMESPACE" get pods

# confirm what you are actually connected to before mutating anything
kubectl config current-context
kubectl cluster-info

# fail fast instead of hanging on an unreachable API server
kubectl --request-timeout=30s get nodes
```

> Always set `--request-timeout` in CI. Without it an unreachable API server hangs until the job times out, which turns a thirty-second failure into a twenty-minute one.

## FAQ

### kubectl patch: Usage, Options & Common CI Errors?

kubectl patch applies a partial update to a resource and is the scriptable alternative to edit. Choosing the correct --type (strategic, merge, or json) is what makes it work the way you expect.

### What it does?

kubectl patch RESOURCE NAME -p '<patch>' merges a fragment into the live object. --type=strategic (the default) understands Kubernetes list-merge semantics; --type=merge is a plain RFC 7386 JSON merge that replaces lists wholesale; --type=json applies an RFC 6902 operation list (add/replace/remove at explicit paths).

### Common errors in CI?

The most common mistake is the wrong --type: a strategic-merge patch on a custom resource (which has no merge metadata) silently misbehaves - use --type=merge or --type=json for CRDs. "The order in patch list ... doesn't match" or a list being replaced instead of merged means you needed strategic but used merge.

---

Latchkey runs CI/CD that repairs its own failures. Agent entry points: https://latchkey.dev/agent.txt, https://latchkey.dev/openapi.json, https://latchkey.dev/llms.txt