# kubectl replace --force: Recreate a Resource

> kubectl replace --force deletes and recreates a resource to get past immutable-field errors. Reference for --force, --grace-period, and the disruption it causes.

Source: https://latchkey.dev/learn/command-reference/kubectl-replace-force-recreate  
Updated: 2026-06-30

kubectl replace overwrites a resource with a full manifest; with --force it deletes and recreates the object to apply otherwise-immutable changes.

Some fields cannot be patched or applied in place. replace --force is the escape hatch, at the cost of a delete-and-recreate.

## What it does

kubectl replace overwrites the live object with the provided manifest in a single update; the manifest must be complete. `--force` makes it delete the existing object and create it anew, which is how you change fields the API marks immutable (for example a Job template or a Service clusterIP).

## Common usage

```Terminal
kubectl replace -f deploy.yaml
# delete and recreate to bypass immutable fields
kubectl replace --force -f job.yaml
# recreate immediately, skipping graceful termination
kubectl replace --force --grace-period=0 -f job.yaml
```

## Options

| Flag | What it does |
| --- | --- |
| -f, --filename | Complete manifest to replace with |
| --force | Delete then recreate the resource |
| --grace-period=<s> | Termination grace seconds (0 with --force = immediate) |
| --cascade=<mode> | How dependents are handled on the delete |
| --dry-run=server | Validate against the server without persisting |

## In CI

replace --force is disruptive: it removes the object (and, depending on `--cascade`, its pods) before recreating, so a Service loses its endpoints and a Deployment restarts. Prefer `kubectl apply` or `kubectl patch` first; reach for replace --force only when you hit a genuinely immutable field. Validate with `--dry-run=server` beforehand.

## Common errors in CI

"The <Kind> \"<name>\" is invalid: ... field is immutable" is exactly what drives people to `--force`. "error: error when replacing ... resourceVersion should not be set" means a plain replace got a manifest missing the live resourceVersion; use apply or add --force. "Error from server (NotFound)" with replace means the object does not exist yet; use create or apply instead.

## 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 replace --force: Recreate a Resource?

Some fields cannot be patched or applied in place. replace --force is the escape hatch, at the cost of a delete-and-recreate.

### What it does?

kubectl replace overwrites the live object with the provided manifest in a single update; the manifest must be complete. --force makes it delete the existing object and create it anew, which is how you change fields the API marks immutable (for example a Job template or a Service clusterIP).

### In CI?

replace --force is disruptive: it removes the object (and, depending on --cascade, its pods) before recreating, so a Service loses its endpoints and a Deployment restarts. Prefer kubectl apply or kubectl patch first; reach for replace --force only when you hit a genuinely immutable field. Validate with --dry-run=server beforehand.

### Common errors in CI?

"The <Kind> \"<name>\" is invalid: ... field is immutable" is exactly what drives people to --force. "error: error when replacing ... resourceVersion should not be set" means a plain replace got a manifest missing the live resourceVersion; use apply or add --force.

---

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