Troubleshooting

First checksCopy Anchor Link

Run these on the manager's server, in the folder with Docker Manager's compose.yaml: /opt/docker-manager, or, once Docker Manager manages its own stack, /var/lib/docker/volumes/docker-manager_stacks/_data/docker-manager.

docker compose ps
docker compose logs --tail 200 docker-manager docker-agent

On another server, run docker compose logs --tail 200 docker-agent in the agent's folder, or docker logs docker-agent if you used the single command. For more detail, set the log level to debug (see Configuration).

When you ask for help, the owner can download a support bundle under Settings → General with Download Support Bundle. It never holds passwords, tokens or file contents, but it does hold server names and recent log lines.

Setup says the page was not opened over HTTPSCopy Anchor Link

• Open your https:// address, not http://server:8080.
• The address must match DOCKER_MANAGER_PUBLIC_URL exactly.
• Docker Manager can't see that your proxy used HTTPS. Add the proxy's IP address to DOCKER_MANAGER_TRUSTED_PROXIES in .env and run docker compose up -d.

A server stays offlineCopy Anchor Link

Check the agent's log on that server. Usual causes:

• On other servers, DOCKER_AGENT_MANAGER_URL must be your https:// address.
• The agent doesn't trust your certificate (see Your own certificate authority).
• The install command was used already or expired. Create a new one.
• The agent is older or newer than Docker Manager. Upgrade whichever is older (see Upgrade).

Docker is already connected through another agentCopy Anchor Link

The server already has an agent in Docker Manager. To replace it, choose Remove Agent on the environment's Agents tab, then re-attach it. Don't use Add Environment for a server Docker Manager already knows.

Stack actions are refused because of the storage layoutCopy Anchor Link

The Storage Check notice on the server's System tab says what is wrong. Usually the agent's mount of Docker's volume folder is missing or wrong (storage_mount_missing or storage_path_mismatch). Keep the agent's volume lines exactly as in the Quickstart, or see Docker's data folder.

Docker Manager can't read a server's disksCopy Anchor Link

The Disk Health card says Docker Manager can’t read this server’s disks. Give the agent privileged: true (see Monitoring).

Charts say Readings Every 10 sCopy Anchor Link

The agent can't read the server's containers directly, so it reads them every 10 seconds. Add cgroup: host and pid: host to that server's agent (see Metrics). If the notice says the server runs cgroup v1, the agent keeps reading every 10 seconds; if it says to upgrade the agent, upgrade it first.

Live views stop updating after about a minuteCopy Anchor Link

Your proxy cuts idle connections too early or holds back responses. Allow idle connections of at least 60 seconds and turn off response buffering. In Traefik, set the entry point's readTimeout to 0s.

Uploads failCopy Anchor Link

Your proxy limits the size of uploads, in the file manager and when you create a stack from an archive. Raise its limit, for example client_max_body_size in nginx. Docker Manager has its own limits too: the File Manager ones, and DOCKER_MANAGER_STACK_ARCHIVE_MAX_MB for stack archives.

"Too Many Tabs"Copy Anchor Link

One account can have 32 live connections, one per open tab. Close tabs you no longer need.

An action on a Docker Manager container is refusedCopy Anchor Link

Docker Manager won't stop, pause, recreate or remove its own containers, or remove its own images, volumes or networks (see Containers). A restart works after you confirm it, except for the agent of the server you act on: it can't restart itself. To upgrade or change Docker Manager, deploy its stack (see Stacks).

A job ended as interruptedCopy Anchor Link

Docker Manager or the agent restarted during the job. Check the result, then start it again. Interrupted or failed deploys, image pulls and update checks have Try Again on their job page.

An update fails because other containers share a container's networkCopy Anchor Link

Some containers use another container's network (network_mode: service:vpn in Compose, or --network container:vpn). Updating that container on its own would cut them off, so Docker Manager leaves it as it is (shared_namespace). Import their Compose project as a stack (see Stacks) so they're updated together, or leave the container out of the update settings.

An update fails while a stack has undeployed changesCopy Anchor Link

The stack has Undeployed Changes, and Docker Manager can't tell which settings its containers run with (unknown_definition): they match neither what it last deployed nor the files on disk, for example after docker compose up with other files, or with a setting it can't compare (such as a config or secret written inline in compose.yaml). It doesn't recreate them. Deploy the stack when its changes are ready (see Stacks); its updates go on from there.

A backup fails because the repository is lockedCopy Anchor Link

Another backup, restore or cleanup is using the same repository (repository_locked). Run it again later, or move the backup schedule away from other jobs on the same repository. Retention, verification and Docker Manager State backups use a repository alone; other backups and restores wait for them.

A backup says Repository MissingCopy Anchor Link

Docker Manager backed up to this location before, but the repository is no longer there (repository_missing). Check the bucket and prefix on the repository's page (More Actions (⋯) → Edit Repository). Docker Manager doesn't create a new repository in its place, so the backup stops until the old one is back.

A backup says Different RepositoryCopy Anchor Link

The repository at this location is not the one Docker Manager backed up to (repository_replaced). Check the bucket and prefix. To start over with this storage, remove the repository and add it again.

Backups are paused after a restoreCopy Anchor Link

Docker Manager was restored from a backup, so it doesn't back up, apply retention or verify until you say so (backup_paused_after_restore). A restore you start still backs up the data it replaces first, unless you turn off Back Up the Current Data First. Re-attach your environments, then press Resume Backups on Backups.

A backup says the environment went offline during the backupCopy Anchor Link

The server lost its connection while its backup ran and didn't come back within six hours (agent_lost). Bring it back online (see A server stays offline), then press Retry Missing on Backups.

A backup says Docker's volume folder can't be readCopy Anchor Link

The agent's container doesn't mount Docker's volume folder at the same path: stack folders were backed up, volumes Docker keeps in its own volume folder were not. Keep the /var/lib/docker/volumes line of the agent's compose.yaml as in the Quickstart, then run the backup again.

A restore is refused while the stack changesCopy Anchor Link

The stack is being renamed, migrated or deleted (stack_changing). Wait for that job to finish, then start the restore again.

A restore says what it restores changedCopy Anchor Link

A volume, a folder or a container the restore had checked changed before it started (restore_target_changed or target_changed). Nothing was changed. Start the restore again from the backup and review it.

A restore says backing up the current data failedCopy Anchor Link

The backup of the current data, taken before anything is replaced, failed (undo_backup_failed). Nothing was restored. Restore again, or turn off Back Up the Current Data First if you don't need Undo Restore. If the message names a stack or container the restore stopped that may serve the repository's storage, restore from a repository it doesn't serve, or leave out the data it uses.

A restore failed and the original data was not put backCopy Anchor Link

Putting the restored data in place failed, and so did putting the original data back (restore_rollback_failed). The containers stay stopped and an alert is raised. The restore's job page names the folders that hold the original data: move it back from there, then start the containers.

Importing a backup says the key is wrongCopy Anchor Link

Check the Recovery Key for typos and enter the newest one you saved (backup_import_key_rejected): it opens older backups of Docker Manager State too. If Docker Manager's secret key file was replaced since that backup (backup_import_key_rotated), or an environment's backups were not moved to the newest key yet, open The key was rotated recently and enter the older key under Previous Recovery Key.

After you rotate the Recovery Key, keep the previous key until the next Docker Manager State backup ran: older Docker Manager State backups open with the new key only from then on. The repository's page says so meanwhile.

A repository's address is not allowedCopy Anchor Link

Docker Manager doesn't connect to loopback, link-local or multicast addresses, such as localhost or 127.0.0.1 (address_not_allowed). Enter the storage's address on your network instead, for example the name or IP address of the server MinIO runs on.

A test message failsCopy Anchor Link

The message, and the channel's Failing status, name the cause. Usual fixes:

• Docker Manager could not connect to the service., The server name in the address could not be found. or The service did not answer in time.: the service must be reachable from Docker Manager's server. Check the server name and port in the address, and the firewall.
• The secure connection failed.: for email, match Port and Encryption (587 with Explicit TLS (STARTTLS), 465 with Implicit TLS); a self-signed certificate is refused.
• The service refused the credentials., The service rejected the message. or The service did not accept the message.: press Edit → Show Address and check the token, password, webhook URL, chat, topic or recipients. A webhook deleted in Discord or Slack needs a new URL.
• The service redirected to another address.: enter the address the service redirects to.
• A test message was just sent: wait a few seconds and try again.

Moving Docker Manager: the new server waits for the old oneCopy Anchor Link

The status page on the new server says what is wrong:

• Old Server Not Answering: from the new server, http://<old server's address>:8080 must open Docker Manager. Check the address and the old server's firewall.
• Pairing Code Does Not Match: DOCKER_MANAGER_MOVE_CODE in the new server's .env must be the code from the newest setup files the old Docker Manager showed.
• Servers' Clocks Differ Too Much: set the clocks of both servers right (turn on time synchronization). The move goes on by itself.
• This Docker Manager Is Older Than the Old One: upgrade Docker Manager on the new server. Run docker compose pull and docker compose up -d there.

Locked out of the owner accountCopy Anchor Link

On the manager's server, in the folder with Docker Manager's compose.yaml (see First checks), run:

docker compose exec docker-manager docker-manager owner-recovery

It prints a link that works once, for one hour. Open it and set a new password. It also removes your sign-in factors: set them up again. If only single sign-on was accepted, passwords and passkeys work again.

Single sign-on says no account is linkedCopy Anchor Link

Your account isn't linked to your identity provider yet. If the owner turned on Link Accounts by Verified Email, the email address of your Docker Manager account and the verified one at your identity provider must be the same: the owner can change yours with Edit Details. New people use their invite link and press Continue with and the name of the identity provider.

Single sign-on can't reach the identity providerCopy Anchor Link

Docker Manager's server must reach the Issuer URL: check the address, that it uses https://, and that the identity provider reports exactly this issuer (with or without a trailing slash). The message says which step failed.

An upgrade failedCopy Anchor Link

Before an upgrade changes its database, Docker Manager saves a copy. If it doesn't start after an upgrade, go back: run these in the folder with Docker Manager's compose.yaml (see First checks).

1. Stop it and list the saved copies:

   Copy Text

   docker compose stop docker-manager
   docker compose run --rm --no-deps docker-manager snapshots list

2. Restore the newest one (the last line):

   Copy Text

   docker compose run --rm --no-deps docker-manager snapshots restore <file name>

3. In compose.yaml, set image: of docker-manager to the version you had before and run docker compose up -d docker-manager.