Docker / Editorial solution guide

Container exits and permission failures: separate process from storage

Identify the first failure and the effective user, executable, and mount before changing authority or ownership.

About 4 min readContent reviewed

Read-only knowledge base ยท No public comments

Recognize the symptoms

A service exits immediately, repeatedly restarts, or reports Permission denied or Read-only file system. docker exec may then fail because the container is not running; that secondary error does not explain the original startup failure.

A replacement image works without a mount but fails when the data volume is attached. Files that were present in the image can also appear missing after a bind mount obscures their target directory.

Understand the likely causes

  • The main command may finish normally, reference a missing executable or interpreter, or receive a runtime command override. Exit codes need state and log context rather than one universal interpretation.
  • The runtime uid, user-namespace mapping, mount ownership, read-only flag, or platform security label can deny access. COPY --chown only changes image content and does not repair a separate host-backed mount.

Preserve state and the first relevant logs

Use an existing authorized diagnostic connection and the actual container identity, not an assumed generated name. Read retained state and bounded logs before restarting anything. Exit zero may mean a one-shot command completed; exit 137 commonly reflects SIGKILL and needs OOM and event evidence. Never turn either observation into an automatic instruction to increase memory or run as root.

bash Read previous state without starting another process 
docker container inspect parcel-api --format '{{json .State}}'
docker logs --timestamps --tail 80 parcel-api

These commands do not repair or restart the target. Existing logs may include sensitive content, so retain only necessary redacted evidence. If the container was removed, use the retained operational record rather than creating an unrelated replacement and assuming it reproduces the same failure.

Check executable and foreground lifetime

Compare the actual Path and Args with the reviewed image command. Check working directory, interpreter availability, executable permission, architecture, and script line endings where relevant. A shell that backgrounds the real server and exits leaves no main service process to supervise. A minimal runtime may intentionally lack a shell; its absence is not permission to modify a production image interactively or keep the container alive with an unrelated sleep loop.

Compare effective user and mounted content

Inspect selected identity and mount fields without dumping the full environment. The synthetic image uses uid and gid 10001, but the effective container may override them. A bind target hides image content, and a read-only mount forbids writes regardless of ordinary file ownership. Rootless and user-namespace setups add host mapping considerations. Identify which exact operation fails and which backing resource supplies that path.

bash Narrow identity, startup, and mount evidence 
docker container inspect parcel-api --format '{{json .Config.User}}'
docker container inspect parcel-api --format '{{json .Path}} {{json .Args}}'
docker container inspect parcel-api --format '{{json .Mounts}}'

No ownership, permissions, data, or daemon configuration is changed. Mount metadata can expose host paths; redact before sharing. Compare these runtime facts with the approved model instead of assuming a Dockerfile USER or COPY ownership remains effective after runtime overrides and mounts.

Apply a narrow correction through the owner

For a missing executable, rebuild the reviewed final image with the required artifact and correct command. For an obscuring mount, correct the source or target through the deployment model. For a legitimate writable data path, coordinate numeric ownership, identity mapping, permissions, and labeling with the storage owner. For a read-only root, provide only the required temporary or persistent write location. Broad privileged mode, world-writable directories, and deleting volumes do not establish which failure was fixed.

Verify the fix

Rehearse the corrected image and storage contract in an approved disposable environment or isolated restore target. Verify foreground service lifetime, required read/write operations under the final identity, retained original records, bounded shutdown, and no unexpected restart loop. Record the effective image and mount identities; this guide performs no engine action or data change.

Keep it from recurring

  • Version command and storage requirements together, test non-root and read-only operation early, preserve first-failure logs, and document ownership initialization separately from application startup. Never treat container replacement as authorization to recreate or delete authoritative storage.

Official references