Repository navigation
Troubleshooting
Common problems and how to fix them.
Symptom: You open Cockpit but there is no "Docker Compose" entry in the left navigation.
Causes and fixes:
-
Package not installed in the right location. The plugin files must be at
/usr/share/cockpit/cockpit-compose/. Verify:ls /usr/share/cockpit/cockpit-compose/
If empty or missing, reinstall the package or re-run the manual install steps.
-
Cockpit cache. Hard-refresh the browser (
Ctrl+Shift+R/Cmd+Shift+R) or clear site data and reload. -
Development symlink missing. In dev mode, the symlink must point to
src/, not the repo root:ls -la ~/.local/share/cockpit/cockpit-compose # Should point to .../cockpit-compose/src
Symptom: The dashboard shows an error like permission denied while trying to connect to the Docker daemon socket.
Fix: Add your user to the docker group and re-log in:
sudo usermod -aG docker $USER
# Log out and back in, or:
newgrp dockerIf you use rootless Docker, the plugin detects the per-user socket automatically — no DOCKER_HOST
shell configuration needed. If both a rootless and a rootful socket are present and the wrong one
is active, use the Rootless / Rootful toggle next to the runtime switch to pick explicitly (see
Podman Compatibility — the same toggle applies
to Docker). Setting DOCKER_HOST in your own shell has no effect on the Cockpit bridge process and
is not read by the plugin.
Symptom: You have running stacks but the dashboard is empty.
Causes and fixes:
-
Wrong runtime selected. Check the Runtime toggle in the toolbar — if you started stacks with Docker but the toggle is on Podman (or vice versa), switch to the correct runtime.
-
Stack not started with
docker compose. Stacks started viadocker rundirectly or via a different tool (e.g., Portainer) are not tracked by Compose and will not appear. -
Compose project name mismatch. The plugin uses the
COMPOSE_PROJECT_NAMElabel that Docker attaches atuptime. If the stack was started without the Compose CLI, it may not have this label. -
Podman +
podman-composelimitation. The Pythonpodman-composedoes not supportcompose ls. The plugin falls back topodman pslabel discovery, which may miss stacks started outside Cockpit Compose. Try bringing the stack down and back up from inside the plugin. -
Wrong socket mode (rootless vs. rootful). If you started a stack with
sudo podman compose up(system-wide/rootful) but the plugin is using the rootless socket, or vice versa, it won't see it. Check the Rootless / Rootful toggle next to the runtime switch and pick the mode matching how you started the stack — see Podman Compatibility. Also make sure Cockpit's administrative access is enabled, since rootful discovery escalates via it. -
Administrative access is off and the Rootless/Rootful toggle isn't showing at all. If Podman's rootless socket genuinely isn't present (see cause 5) and the rootful one can't be confirmed because Cockpit's Administrative access isn't enabled yet, the toggle used to just disappear as if nothing were detected. It now instead shows a disabled Rootful option with a tooltip explaining this — turn on Administrative access (in the Cockpit page header, not inside this plugin), then click the small refresh icon next to the toggle to recheck.
-
upreports success but the stack still shows down (Podman mode, Docker also installed). This was a real bug: when Podman'scomposesubcommand can't reach any confirmed Podman socket, it may delegate to an installeddocker-compose-pluginbinary, which — with no explicit socket to target — silently falls back to its own default, i.e. a completely separate Docker engine, if one happens to be installed alongside Podman. The command then genuinely succeeds, just against the wrong engine, so Podman-based discovery never sees it. Fixed: the plugin now always points Podman-mode compose commands at either a real, confirmed socket or a deliberately unreachable one, so this now fails loudly (visible in the Up/Down progress dialog) instead of silently succeeding on the wrong engine. If you hit this, it almost always means cause 6 above — Administrative access needs to be turned on.
Stack shows "running" but its services/containers show stopped, or Stack Info is empty (rootful Podman)
Symptom: The stack card correctly shows a running status, but expanding it or opening Stack Info shows services as stopped/exited, or no container details at all — even though the containers are genuinely running and producing logs.
Cause: This was a real bug, fixed in a later release than the one that first fixed rootful
discovery (issue #242): stack-level
status and the service/container-level detail view are powered by two separate code paths, and
only the first one was updated to escalate correctly for rootful Podman. If you see this,
update to the latest release — no configuration change fixes it. The same underlying gap also
made a stop/down issued while viewing Rootless mode look like it affected the Rootful stack
too (it didn't — the service-level view just always displayed rootless data regardless of which
mode was actually selected, which was misleading but harmless).
Docker still lists some of the stack's containers. The Down dialog names them and offers Force remove, which removes them by project label even when the compose file is gone. If it says the containers' records are damaged, use Repair (Docker only) — note that it briefly stops Docker and every container on it. See Managing Stacks → When containers are left behind.
Symptom: The Logs modal opens but lines stop arriving after a while.
Fixes:
- Click ↺ Refresh in the Logs toolbar to restart the stream.
- If the container has stopped, there are no more lines to stream — the stream ends naturally.
- The modal keeps only the most recent 500 lines, so older output scrolls away on busy services. Use Download to keep a copy, or filter by service or level.
Symptom: Your compose file is accepted by docker compose but the editor highlights errors.
Cause: The editor validates against the Docker Compose JSON Schema. Some valid real-world fields are not covered by the schema (custom extensions, newer Compose spec features).
Fix: You can save despite schema warnings — the confirmation prompt asks "Save anyway?" Click Save to proceed. The schema errors are advisory and do not block saving.
Symptom: Opening a shell into a container gives OCI runtime exec failed: container not found or similar.
Causes:
- The container is in a restarting or exited state — wait for it to be fully running.
- The specified shell command doesn't exist in the image. Many minimal images (Alpine, distroless) only have
/bin/sh, not/bin/bash. Change the Command field to/bin/sh.
Symptom: Starting a stack in Podman mode fails with an error about nftables or NETAVARK.
Fix: Install passt, which provides an alternative networking backend:
# Arch
sudo pacman -S passt
# Fedora
sudo dnf install passt
# Debian / Ubuntu
sudo apt install passtSymptom: Switching to Podman mode fails with a socket or connection error.
Fix: Enable the Podman user socket:
systemctl --user enable --now podman.socketFor system-wide (root) Podman:
sudo systemctl enable --now podman.socketAfter enabling either socket, click the small refresh icon next to the Rootless / Rootful toggle (next to the runtime switch) to recheck — this re-detects the sockets and actively probes each one, so it also catches a socket that exists but whose daemon isn't actually responding.
Symptom: npm run vm:init starts but the VM never becomes ready.
Fixes:
- Check the serial console:
./scripts/test-vm.sh logs arch(replace with your distro). - Confirm QEMU and
cloud-image-utilsare installed. - Confirm QEMU has
virtfs/9psupport (qemu-fullon Arch includes it; theqemupackage does not). - If the VM's overlay disk is corrupted, wipe and re-provision:
./scripts/test-vm.sh clean arch.
See VM Testing for the full command reference.
Cockpit Compose
Using the UI
- Stacks Dashboard
- Managing Stacks
- Bulk Actions
- Background Tasks
- Viewing Logs
- Editing Configuration
- Stack Info
- Pulling Images
- Events
- Process Viewer
- Shell Access
- Running Commands
- Prune Resources
- Scaling Services
Stack Management
Runtime Support
Help
Development