Troubleshooting

Start with the output of the failing command, then inspect state and logs.

dpl inspect <unit>

Common log paths:

<base>/state/<unit>/log/build.log
<base>/state/<unit>/log/runtime.log
<base>/state/<unit>/log/access.log   # http-server only
<base>/state/<unit>/log/timers.log

Podman is not installed

Symptom:

podman: command not found

or a deploy fails when dpl tries to build or run a container.

Fix:

podman --version

If that fails, install Podman for your operating system. Then rerun the deploy:

dpl deploy <unit>

The install script prints a warning when Podman is missing. dpl still installs, but deploys cannot run containers until Podman exists.

dpl serve is not started

Symptom:

• dpl deploy updates state, but the container does not start.
• Timers do not run.
• dpl inspect shows a unit waiting for startup.

Fix on a systemd host:

systemctl status dpl
systemctl start dpl

Fix when running manually:

DPL_BASE=/opt/dpl dpl serve

Use the same DPL_BASE for dpl serve and your deploy commands.

After starting serve, redeploy or reload the daemon:

systemctl reload dpl

or send SIGHUP to the process that owns state/serve.pid (for example, kill -HUP $(cat state/serve.pid)).

A reference is broken

Symptom:

Invalid reference
unknown export
unit '...' not found

Fix:

dpl check <unit>

Check that:

• the referenced unit has a YAML file in conf
• the unit name uses lowercase letters, digits, and dashes
• the reference key is valid for that unit type
• the secret exists

App starts and then fails health check

Look at the runtime log:

tail -n 100 /opt/dpl/state/<unit>/log/runtime.log

Common causes:

• the app listens on a different port than runtime.port
• a required environment value is missing
• runtime.init failed
• the database is not ready

Fix the config or app code, then deploy again.

HTTP requests fail or return the wrong status

For an http-server unit, nginx access records are stored separately:

tail -n 100 /opt/dpl/state/<http-server>/log/access.log

access.log is JSONL and contains only nginx access records. nginx error output is in the same unit’s runtime log:

tail -n 100 /opt/dpl/state/<http-server>/log/runtime.log

Static files return 404

Check the app export and domain route:

exports:
  - source: /app/dist
    path: /

routes:
  - kind: serve_files
    location: /
    root: ${site:export}

Then deploy in this order:

dpl deploy site ./site.tar.gz
dpl deploy domain

The domain deploy needs the app export to already exist.