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 openCopy Anchor Link

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.

PostgreSQL uses more disk space than expectedCopy Anchor Link

The PostgreSQL volume includes every database in that PostgreSQL instance, their indexes, transaction logs (WAL), and space available for PostgreSQL to reuse. It is larger than the active Citadel database alone. An older database retained during a reinstall or recovery remains in the same volume until an administrator explicitly removes it. Check its recovery purpose and backup before removal; having no current connections alone does not prove it is disposable.

Statistics retain seven days of history. Container and workload charts share measurements while keeping workload ownership separately, so redeploying or removing a container preserves its workload history without a second metric copy.

You still choose the polling interval with CITADEL_STATS_POLL_INTERVAL_SECONDS in the Compose environment file. The newest 24 hours keep that sampling resolution. Background maintenance combines older container/workload/Swarm-task samples, platform host gauges, and node I/O into minute summaries, preserving weighted averages and reset-aware network/disk totals. Sparse minutes and the newest observation stay raw. Platform minutes also stay raw when per-container density or the estimated replacement size would make summarizing unhelpful; even 10-second polling can remain raw when PostgreSQL compresses its JSONB very well. Charts for ranges starting more than 24 hours ago use at least minute resolution throughout, including a recent raw tail; recent short ranges retain finer detail. Older charts have minute resolution; a custom time range that cuts through a summary omits that partial minute instead of including traffic outside the range. Pending platform alerts remain raw until processed. Their source's compaction stops before the pending minute; other hosts/nodes can still compact. Raw host/node tables keep their existing layout and reuse freed space through vacuuming.

Daily partitions release their files when the whole day expires; empty raw partitions are also removed after compaction. Partial-day and fallback-partition expiry still uses bounded deletes. Normal vacuuming makes that deleted space reusable, so the volume need not shrink immediately. WAL and other PostgreSQL databases are separate from this history optimization. See PostgreSQL partition maintenance and routine vacuuming.

The storage migration copies existing measurements into the shared tables before removing the old copies, so the upgrade needs temporary room for those tables and WAL. Older-history compaction then catches up on a separate 30-second cadence within the same maintenance job, bounded to five seconds and 128 passes per tick. It does not repeat the slower retention sweep for every source-hour; its savings are gradual rather than part of the startup migration. While platform history catches up, new summaries can temporarily increase allocated disk space: deleted raw pages become reusable, but are not forcibly returned to the filesystem.

Compare database and table/index sizes before deciding whether storage is growing unexpectedly. Never delete files from the PostgreSQL volume to reclaim space.

A Platform stays offlineCopy Anchor Link

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.

If the dashboard opens but an Edge Agent keeps reconnecting, check the gRPC routing through your proxy or CDN. A healthy browser/API endpoint does not verify Edge connectivity.

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

Live updates stopCopy Anchor Link

The header reports the browser's connection to Citadel Core:

This connection is separate from a Platform's Agent connection. An interruption does not by itself mean that Docker workloads stopped. Once connected, check the workload and its operation history before repeating a command.

Core checks the main live-update connection with a WebSocket Ping every 30 seconds and closes it if the matching Pong does not arrive within 15 seconds. Browsers respond automatically, including while you are not typing. A detected connection loss releases its live subscriptions and interactive terminal; claimed deployments and other durable operations continue independently.

If the problem persists behind a reverse proxy, check WebSocket upgrades and long-lived connection timeouts. See TLS and secure Agent transport or the Caddy example.

An action is unavailableCopy Anchor Link

Check the disabled action's explanation, then review:

• Access: your Role and any resource-specific permissions. Seeing a resource does not grant permission for every action; see access control.
• State: wait for an operation in progress, restore the Platform connection, or refresh stale container information.
• Ownership: manage Swarm Tasks through their Service or Stack. Citadel's own system containers are protected from ordinary lifecycle actions.
• Selection: inspect one resource at a time; group actions require eligible targets. Networks and volumes in use cannot be deleted from their lists.

For an option marked as license-restricted, check feature availability. A license change does not replace the user's permissions or the action's runtime requirements.

A resource or account is missingCopy Anchor Link

Clear list filters and try global search. Search only returns resources your account can read. Ask an administrator to review your Roles, enabled Team memberships, and direct grants if expected access is missing. An empty Updates available list only means no detected updates match the current filters.

For sign-in problems, check the account's enabled state, use an MFA recovery code when applicable, or follow OIDC troubleshooting. Another administrator can help recover a local account. Restarting Core does not reopen setup; do not delete installation data to reset a password.

A container terminal will not connectCopy Anchor Link

The container must be running and your account must have terminal access. Choose sh if the image does not include bash; some minimal images have no shell. For a Swarm Task on another Node, verify node coverage. If logs and statistics also stop updating, check the browser connection above.

See container tools for the normal workflow and volume troubleshooting for file access problems.

An application will not deployCopy Anchor Link

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 openCopy Anchor Link

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.

Configuration changed but the application did notCopy Anchor Link

Saving a Stack, Deployment, or binding changes Citadel's desired configuration. Deploy or apply the consuming resource to change its runtime. Check which image, commit, and release actually ran; update checks detect changes without applying them.

For unresolved or stale secret values, use binding troubleshooting. For image pulls or Build pushes, use registry troubleshooting.

An alert arrives, or an expected notification is missingCopy Anchor Link

Open Alerts and inspect the event's resource, time, and Info. Check the resource's current state before acting on an older notification. Acknowledge while investigating and resolve after verifying recovery; neither action changes the workload. See responding to an alert.

If no message arrives, first check whether Citadel created an event. No event points to rule evaluation, scope, or unavailable observations. An event without a message points to channel assignment or delivery. Follow alert troubleshooting for each case.

Get helpCopy Anchor Link

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.