Troubleshooting

Start with the error shown in Citadel's operation panel or Activities page. Wait for the current operation to finish before trying it again.

Citadel will not open

From your installation directory, run:

docker compose ps
docker compose logs --tail=100 server pg_db

• For the supplied local setup, use http://localhost:18000, not port 8000.
• Open that address on the machine running Citadel. For another machine, use your configured HTTPS address.
• If PostgreSQL cannot start, check PG_PASSWORD and persistent storage. Changing its initial password in .env does not reset an existing database password.
• If an image download fails, check the image address, version, and registry access in .env.

A Platform stays offline

Check Docker is running on the target host. For a regular Agent, check its container and whether Core can reach its Agent address. For an Edge Agent, check enrollment and whether it can reach Core's gRPC address. Follow Agent troubleshooting or Edge Agent troubleshooting.

For Swarm, check manager health and node-agent coverage. Adding another Platform record for the same Docker engine will not repair connectivity.

An application will not deploy

Read the failed operation's error. Check the image name and registry access, whether the host port is already used, and whether the requested volumes exist. For a Stack, fix editor or preflight errors before selecting Deploy. Saving configuration alone does not deploy it.

The application is running but its page will not open

Use the Docker host's address and the published host port, not the container port. Check the application's logs, port mapping, and host firewall. A running container does not always mean the application inside it is ready.

Get help

Report reproducible defects in GitHub Issues. Include the Citadel version, Platform and connector type, what you expected, what happened, the time of the failed operation, and the relevant error text.

Remove passwords, tokens, secret values, and personal data from logs and screenshots. Do not attach .env, private keys, or a database dump.