Troubleshooting

Docker Compose

Symptom	What to do
Docker reports permission denied or cannot connect	Your account cannot use Docker, or Docker Engine is not running. docker version must show a server section.
Setup refuses a placeholder or short DB_PASSWORD	Generate one with the sed command from Installation before the first setup. Never change it afterwards.
Set VAULTIGEN_IMAGE_TAG / VAULTIGEN_DOMAIN / DB_PASSWORD in .env	Run the command in the directory that holds compose.yaml and .env, and fill in the value.
No HTTPS certificate	Check VAULTIGEN_DOMAIN, the DNS records (including IPv6) and that ports 80 and 443 reach the server from the internet. Read docker compose logs --tail=100 web.
The page does not open	docker compose ps, then the web logs. Check that nothing else uses ports 80 or 443; otherwise use the proxy override.
Behind a proxy, every user has the proxy’s IP address, or redirects use http://	The proxy must forward X-Forwarded-For and X-Forwarded-Proto. A proxy that is not on the same host needs VAULTIGEN_TRUSTED_PROXIES; rootless Podman needs 172.31.250.10.
Web, worker and scheduler do not start after an update	docker compose logs --tail=100 migrate. Fix the reported backup, key or migration problem, then docker compose up -d --wait. Do not bypass migrate.
Setup or migrate reports missing keys for an existing installation	Unpack your key copy into data/ or restore. Never delete files or generate new keys to get past the error.
An edited .env has no effect	Run docker compose up -d --wait; restart keeps the old settings.
Permission denied on data/ or backups/ from the host	Expected: they belong to the container users. Use sudo to read them and never change their owners.
Disk full	df -h. Copy old sets off the server, then remove them from backups/ or enable retention. A backup needs room for a temporary snapshot and the finished set.

Installation and keys

Symptom	What to do
“Installation security configuration is missing or invalid”	Check that vaultigen:initialize ran, that PHP can read installation.json, and that environment overrides match the original installation. Clear the config cache and restart workers.
“Installation identity already exists”	Initialization runs once. Continue with migration or bootstrap. Never delete the identity file to silence this message.
“The installation KEK key file is missing or unreadable”	Restore the escrowed kek.json. Only on a brand-new installation without vault data may you run vaultigen:kek:generate.
“Vaultigen cannot resolve its installation encryption keys”	The panel fails closed until the KEK keyring is available. Restore it; never replace it on an existing installation.
Missing Vite manifest or unstyled pages (manual installation)	Run npm ci && npm run build in the installation directory.

Sign-in and second factors

Symptom	What to do
Authenticator codes are rejected	Check the clock on the server (NTP) and on the phone. For re-authentication, wait for a new code if the current one was already used.
No email code arrives	Check mail delivery on Installation status, then use Resend. Codes expire after four minutes and sending is throttled.
“Remember this device” is missing	An admin has to set a non-zero period under Settings → Authentication.
A user is locked out	A Super Admin uses Reset authentication on the user. For a sole administrator, see Authentication.

Users and seats

Symptom	What to do
“User limit reached”	All seats are in use. Cancel an open invitation, deactivate a user, or install a license. See Licensing.
An invitation email was not sent	Fix the mail transport, then Resend from the invitations list.

Background work

Symptom	What to do
Queue or scheduler “Not verified”	Start both processes (on Docker Compose: docker compose up -d --wait, then check docker compose logs worker scheduler), wait a minute, refresh Installation status.
A backup or import stays queued	The queue worker is not running. Start it; queued jobs are picked up automatically.
Security notifications stay pending	Mail is not delivering. Fix the transport; the scheduler retries.
Storage headroom warning	Move old backup sets off the host and check PHP’s temp directory.

License

Message	Meaning
This is not a valid Vaultigen license	The block is incomplete. Paste it again including the BEGIN and END lines.
The license signature is not valid	The text was changed. Copy it again from the email or your account.
Not signed with a key that this Vaultigen version trusts	Your Vaultigen version is older than the license. Update Vaultigen.
This license requires a newer Vaultigen version	Update Vaultigen.
License does not cover this version	The version was released after your update period. Renew, or go back to a covered version.

Still stuck? Write to the address at the bottom of this page with the exact message, the Vaultigen version and what you tried. Never send passwords, keys or license files you do not want to share.