Debug a container that works on your laptop but not the server

A container starting on a laptop does not prove that the server runs the same artifact under the same conditions. The laptop may use a bind-mounted source tree, a different CPU architecture, cached files, or host services that the deployed container cannot reach. The useful question is not why Docker behaves differently. It is which assumption differs between the two executions.

Use an illustrative Node application that starts locally but exits on the server. No particular error is assumed. The investigation should narrow the difference with observable evidence before editing the image or deployment configuration. Randomly changing permissions, base images, and ports together can hide the cause and create a larger operational problem.

Confirm the exact artifact

Record image digest, tag, build source revision, and deployment configuration in both environments. A mutable tag can refer to different images at different times. If local execution uses a newly built image while the server pulls an older tag, the first mismatch is already established. Compare immutable identities rather than relying on a shared label.

Check whether local development mounts source code or dependencies over files in the image. Those mounts can hide missing build output and accidentally supply packages not included in the production artifact. Run the production image locally without development bind mounts, using synthetic configuration. This does not recreate the server completely, but it tests whether the image is independently runnable. Keep development convenience separate from the claims made about the deployable artifact.

Check CPU and runtime compatibility

Compare host architecture with the image's supported platform. A laptop and server may use different architectures, and native dependencies may be compiled for one of them. Verify the selected image variant and any build-stage assumptions. Multi-platform image support must include compatible dependencies, not only a platform label.

Inspect the runtime version and operating-system libraries used by native modules. A dependency installed in one build environment may not work when copied into a materially different runtime image. Prefer a clear build pipeline with compatible stages. Do not add emulation as the first fix without understanding the target platform and operational cost. If a cross-platform build is intended, document the platforms that were actually built and tested.

Inspect files and process startup

Read the container exit code and the earliest startup logs. Check the working directory, entry command, required compiled files, and file-name casing. A case-insensitive development filesystem can conceal an import that fails on a case-sensitive server. Confirm that the final image contains the artifacts expected by the start command.

Use a minimal inspection step in an isolated container rather than copying private configuration out of production. List only relevant paths and package versions. Check whether a startup script assumes a shell or utility absent from the runtime image. If the process exits because a required file is missing, fix packaging or the command directly. Broadly installing tools can make the symptom disappear while leaving the artifact contract unclear.

Compare users and writable locations

A development container may run as root while the server runs as an unprivileged user. Determine which directories need writes for logs, temporary files, uploads, and caches. Prefer writing to explicitly mounted or designated locations rather than the application source directory. A read-only root filesystem can be compatible with the application if writable needs are planned.

Do not solve a permission error by making every file world-writable. Identify the specific path, required owner, and operation. Verify mount ownership and filesystem semantics in the deployment. Also consider whether temporary files must survive restarts. If they do, they are durable state and need appropriate storage, not a convenient directory inside the container. The diagnosis should distinguish permission, path, and persistence requirements.

Trace environment and network assumptions

List required configuration names without printing their values. Check which are present and valid at runtime, and distinguish build-time values from runtime injection. A successful image build does not mean deployment secrets exist. Fail startup clearly for required configuration, while treating optional feature settings deliberately.

Inside a container, localhost refers to that container's network context, not necessarily the laptop's database or the server host. Inspect database and provider hostnames, ports, DNS, and network policy. Confirm that the application listens on the intended interface and port. A process can be healthy while inaccessible because it binds only to loopback. Use controlled connectivity checks and redacted errors; avoid dumping environment variables or credential-bearing URLs into logs.

Reproduce one difference at a time

Build a comparison artifact with local value, server value, and evidence for image, platform, command, user, mounts, configuration presence, and network target. Choose the strongest mismatch and reproduce it locally if feasible. Running as the server user or removing a bind mount can expose the failure without touching production.

Change one bounded factor and verify the original symptom. If startup succeeds, also check the actual user journey and required storage behavior. An application that no longer exits may still fail on the first upload or database query. Keep the original logs and artifact identities in the incident record. They allow another developer to distinguish a packaging correction from a deployment configuration correction and prevent the next build from reintroducing the assumption.

Add a meaningful deployment check

After the fix, add a lightweight check for the failure class. Verify production-image startup without development mounts, target-platform packaging, or required configuration presence as appropriate. Do not add a broad end-to-end suite when a packaging assertion catches the issue more directly.

Use readiness separately from process startup if the application depends on initialization. A server should not receive normal traffic merely because its command is still running. See useful health checks for the distinction. Record which platforms and deployment conditions remain unverified. Container consistency reduces environment drift, but external services, permissions, and network configuration still require deliberate handling.

Use AI on sanitized comparison evidence

Provide startup errors, Dockerfile, deployment command, and a redacted comparison table. Ask the assistant to rank likely mismatches and suggest read-only inspections. Require it to explain which hypothesis each inspection would confirm. Do not provide a complete production environment dump.

Verify proposed flags and APIs in official documentation for the tools you use. An assistant may conflate host and container networking or suggest changes that apply to another platform. Review its recommendations for scope: changing a base image or running as root may create wider risk than correcting one path. AI is useful for organizing evidence, but the exact artifact and execution context must decide the diagnosis.

Sources

Docker multi-platform build documentation explains platform-specific artifacts and build approaches.

Kubernetes probe documentation provides a primary reference for startup and traffic-readiness checks when Kubernetes is used. The troubleshooting sequence is illustrative.