Error from server (AlreadyExists): An object with that name already exists in the namespace

Names must be unique per kind per namespace. A create against an existing name is rejected, which is why kubectl apply exists as the idempotent alternative to kubectl create.

Applies to: All Kubernetes versions

What it means

Object names are unique within a namespace for a given resource kind, and create is strictly a create — it fails if the name is taken. This is the intended behaviour and is what makes create safe to use when you want to be certain you are not overwriting something. The idiomatic alternative is apply, which creates or updates as needed and is what belongs in any automated pipeline. A less obvious version of this error involves generated names: a controller creating objects with a generated suffix can still collide if it is using a fixed name, and a failed cleanup can leave an object behind that blocks recreation.

Most common causes

• Running kubectl create against an object that already exists.
• A pipeline using create where apply was intended, so the second run always fails.
• A previous deletion that has not completed, often because a finalizer is holding the object.
• Two controllers or two pipelines managing the same object name.
• A retry after a request that actually succeeded, where the response was lost.
• A Job or similar object left behind from a previous run under the same fixed name.

How to diagnose it

1. Inspect what is already there: kubectl get RESOURCE NAME -n NAMESPACE -o yaml.
2. Check whether it is being deleted: look for deletionTimestamp and finalizers in that output.
3. Check who created it: kubectl.kubernetes.io/last-applied-configuration and managed fields give some history.
4. Look for a second pipeline or controller managing the same name.

How to fix it

1. Use kubectl apply for anything run more than once. It is declarative and idempotent, which is what automation needs.
2. Delete the existing object first, if replacing it is genuinely intended and its data is not needed.
3. Resolve a stuck deletion by finding out why its finalizer is not being removed.
4. Use generateName instead of name for objects that should be unique per invocation, such as one-off Jobs.
5. Ensure only one system owns each object, since two writers produce a fight that neither wins.

Notes

kubectl apply and kubectl create are not interchangeable in the other direction either: apply records the applied configuration and performs a three-way merge on subsequent runs, which is what allows fields removed from a manifest to be removed from the object. Switching a resource from create to apply partway through its life can therefore behave unexpectedly on the first apply.

Related

• Error from server (Conflict) — The object was modified by someone else
• Error from server (NotFound) — The named object does not exist

Sources

• Kubernetes documentation — Object Names and IDs
• Kubernetes documentation — Server-Side Apply
• Kubernetes documentation — Finalizers