duplicate key value violates unique constraint "unique_constraints_pkey" on configuring step

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 "uniqueconstraintspkey" 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

In gh:zitadel/zitadel#8910 the issue was: Issue zitadel/zitadel#8910 (closed, 25 comments): ### Preflight Checklist

• [x] I could not find a solution in the documentation, the existing issues or discussions
• [x] I have joined the ZITADEL chat

Environment

Self-hosted

Version

2.64.1

Database

PostgreSQL

Database Version

16-alpine

Describe the problem caused by this bug

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... The verified answer: 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:

chown 1000:1000 machinekey

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. Source: https://github.com/zitadel/zitadel/issues/8910