Troubleshooting

Start with the deployment log or the relevant service log. Record the deployment ID, release, environment, and installed version when asking for help. Remove secrets, tokens, and pairing codes from any shared output.

The website does not open

Check DNS, inbound ports 80 and 443, and the Compose services:

docker compose ps
docker compose logs --tail=100 app caddy

Confirm that DURPDEPLOY_URL matches your public HTTPS origin. For the supplied stack, Caddy needs BACKEND=app:8080. Keep backend port 8080 private.

The app cannot read its encryption key

Check that secrets/durpdeploy_key exists and has the mapped ownership required by your runtime. The rootful Docker example uses UID and GID 10001 with mode 0600. Rootless Podman needs its user-namespace ownership mapping. Repeat the key-access check in Install DurpDeploy. Do not generate a replacement key for an existing database.

I cannot create or edit content

Check both your global role and project membership. Deployers can execute existing releases but cannot author steps, variables, or releases. Ask an administrator for the required access. See Users and integrations.

A container step fails before the script starts

Check these items in the failed step’s log:

• The configured Docker or Podman runtime is running and reachable.
• The image reference exists and the runtime can pull it.
• The image contains the selected interpreter, such as bash, pwsh, or python3.
• The staging helper image is cached in the execution runtime.

Server steps require a container image and have no host fallback. Images such as plain Alpine do not include Bash by default. Server containers have no host mounts and no network by default. Use an image with the tools already installed or choose the appropriate execution method.

A remote step has no matching agent

Open Admin → Agents and check the heartbeat, active state, and environment assignment. Confirm that the agent has every capability label required by the step. For container mode, check agent/3, runtime readiness, and interpreter support. See Connect remote agents.

Pairing or agent connections fail

During pairing, check that the server can reach the temporary agent listener. After pairing, check that the agent can reach the server’s dedicated endpoint on port 23187. Do not use the Caddy browser endpoint for agent traffic. Compare fingerprints again if a new pairing is necessary. Preserve existing state while investigating connection failures.

A changed script or variable is missing

Check the release used by the deployment. Project edits do not change an existing release automatically. Create a new release or select Refresh before starting a new deployment.

Check the variable’s environment scope and the step’s Limit variables (optional) field. An environment-scoped value overrides an unscoped value with the same name. See Variables and secrets.

A deployment stays queued or waits for approval

Check for active work in the same project and environment. Approval waits and unconfirmed agent cleanup can keep that pair occupied. Ask a global administrator to review a required approval.

If cleanup is unconfirmed, investigate the original workload on its execution host. Wait for the same agent to reconcile and report readiness. Do not delete state or re-pair an agent to bypass this condition.

Logs stop updating

Reopen the deployment page to reconnect. If it repeats, check the reverse proxy’s streaming and idle timeout settings. Proxies must allow long-lived SSE responses and flush events promptly. See the proxy connection guidance.

Notifications or backups fail

Administrators can inspect notification results at /admin/notifications on their server. Check channel settings and SMTP configuration for failed or skipped deliveries.

For backups, inspect docker compose logs --tail=100 litestream. Check storage credentials, region, endpoint, and the configured replica path. Verify uploaded data after a known database change. See Backups and upgrades.

Get more help

Use the reference library for advanced settings and detailed recovery instructions. When reporting a problem, include the version, expected result, actual result, and redacted error output.