## TL;DR

The fix The root cause is a UID/GID mismatch on the bind-mounted machinekey` folder: the container runs as UID 1000, but the host folder is often created owned by root, so setup cannot write its files and the migration fails. Fix it with: 3. chown 1000:1000 machinekey 4. then restart the stack. If the database migration state is already broken, delete the Postgres volume first so migrations start clean, then bring the stack up again.

## When to use

You are seeing this: Self-hosted ZITADEL deployed with Docker randomly throws migration exception on configuring step: msg="migration failed" caller="[HOME]/..." error="ID=V3-DKcYh Message=Errors.Instance.Domain.AlreadyExists... Use this skill when you run into "duplicate key value violates unique constraint "unique_constraints_pkey" on configuring step".

## When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

## Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

## Steps

1. Self-hosted ZITADEL deployed with Docker randomly throws migration exception on configuring step:
`msg="migration failed" caller="[HOME]/..." error="ID=V3-DKcYh Message=Errors.Instance.Domain.AlreadyExists...

2. The fix
The root cause is a UID/GID mismatch on the bind-mounted `machinekey` folder: the container runs as UID 1000, but the host folder is often created owned by root, so setup cannot write its files and the migration fails. Fix it with:

3. chown 1000:1000 machinekey

4. then restart the stack. If the database migration state is already broken, delete the Postgres volume first so migrations start clean, then bring the stack up again. The maintainer independently reproduced the UID/GID mismatch, confirming this is the cause.

## Why this happens

The fix The root cause is a UID/GID mismatch on the bind-mounted machinekey` folder: the container runs as UID 1000, but the host folder is often created owned by root, so