# kubectl patch --type=json: JSON Patch Operations

> kubectl patch --type=json applies RFC 6902 add/replace/remove operations by path. Reference for op syntax, escaping, and the path-does-not-exist error in CI.

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

kubectl patch --type=json applies an ordered list of RFC 6902 operations (add, replace, remove, test) addressed by JSON Pointer paths.

When you need to remove a key, edit a specific array index, or change a CRD field by exact path, a JSON patch is the precise choice.

## What it does

With `--type=json`, kubectl patch takes an array of operations, each with an `op` (add, remove, replace, move, copy, test) and a `path` written as a JSON Pointer. Array indices are explicit, so you can target `/spec/template/spec/containers/0/image` exactly.

## Common usage

```Terminal
kubectl patch deployment api --type=json -p \
  '[{"op":"replace","path":"/spec/template/spec/containers/0/image","value":"api:v2"}]'
# remove a field
kubectl patch deploy api --type=json -p \
  '[{"op":"remove","path":"/spec/template/spec/containers/0/livenessProbe"}]'
# append to a list with the - index
kubectl patch deploy api --type=json -p \
  '[{"op":"add","path":"/spec/template/spec/containers/0/env/-","value":{"name":"X","value":"1"}}]'
```

## Options

| Field / Flag | What it does |
| --- | --- |
| --type=json | Interpret the patch as RFC 6902 JSON patch |
| op | add, remove, replace, move, copy, or test |
| path | JSON Pointer; ~1 escapes /, ~0 escapes ~ in keys |
| /list/- | The - index appends to an array |
| --patch-file <file> | Read the operations from a file |

## In CI

JSON patch is the only patch type that can `remove` a field, and it works on CRDs since it needs no schema. Escape slashes in annotation keys as `~1`, for example `/metadata/annotations/example.com~1config`.

## Common errors in CI

"the server rejected our request ... add operation does not apply: doc is missing path" means a parent object in the path does not exist; add it first or use a `replace` only when present. "remove operation does not apply: doc is missing path" means the field is already absent. "error: unable to parse ... invalid character" usually means unescaped quotes in the shell; pass the patch from a file to avoid quoting headaches.

## 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 --type=json: JSON Patch Operations?

When you need to remove a key, edit a specific array index, or change a CRD field by exact path, a JSON patch is the precise choice.

### What it does?

With --type=json, kubectl patch takes an array of operations, each with an op (add, remove, replace, move, copy, test) and a path written as a JSON Pointer. Array indices are explicit, so you can target /spec/template/spec/containers/0/image exactly.

### In CI?

JSON patch is the only patch type that can remove a field, and it works on CRDs since it needs no schema. Escape slashes in annotation keys as ~1, for example /metadata/annotations/example.com~1config.

### Common errors in CI?

"the server rejected our request ... add operation does not apply: doc is missing path" means a parent object in the path does not exist; add it first or use a replace only when present. "remove operation does not apply: doc is missing path" means the field is already absent. "error: unable to parse ...

---

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