Introduction

When a container will not start, docker exec is no longer available, so you need a different route to inspect or repair files. The right method depends on where the files actually live: a bind mount, a named volume, or the container’s writable layer.

Check mounts before touching the container

Start by finding out whether the file is already backed by host storage. If it is a bind mount or named volume, you often do not need to modify the stopped container directly at all.

docker inspect my-broken-container --format '{{json .Mounts}}'

If the output shows a bind mount, edit the host-side file instead. That fix survives container recreation and is usually the cleanest path.

For a bind mount, the host path is the source of truth:

ls -la /path/on/host/config

If the problem is in mounted data, fix that data and recreate or restart the container.

Use docker cp for simple file edits

docker cp works on stopped containers, which makes it the easiest option for a broken config file or script.

Copy the file out:

docker cp my-broken-container:/app/config.yml ./config.yml

Edit it locally with your normal tools, then copy it back:

docker cp ./config.yml my-broken-container:/app/config.yml
docker start my-broken-container
docker logs my-broken-container

This method is fast and low-risk for small repairs. It is less convenient if you need to browse a large directory tree or install debugging tools.

Inspect volumes with a helper container

If the important files are in volumes, run another container that mounts the same data. That gives you an interactive shell without requiring the original container to start successfully.

docker run --rm -it --volumes-from my-broken-container alpine sh

Inside the helper shell, inspect the mounted paths and edit them with the tools available in that image. This is particularly useful when a database seed file, uploaded asset, or mounted configuration directory is the real problem.

For named volumes, you can mount the volume explicitly:

docker run --rm -it -v my_app_data:/data alpine sh

That avoids depending on the broken container once you know which volume matters.

Create a debug image from the stopped container

If the file lives in the container’s writable layer and you need broader filesystem access, commit the stopped container to a temporary image and launch a shell from that.

docker commit my-broken-container temp/debug-image
docker run --rm -it --entrypoint sh temp/debug-image

This is a diagnostic technique, not a final deployment process. It is useful when startup fails so early that you cannot inspect runtime state any other way.

You can then copy repaired files out, verify paths, and translate the fix into a durable Dockerfile or configuration change.

Recreate from the original image with a different entrypoint

Sometimes the container-specific filesystem is not the interesting part. The failure may come from the image, startup script, or command line. In that case, run a new container from the same image with a shell entrypoint.

docker run --rm -it --entrypoint sh my-image:tag

This does not include changes made in the failed container’s writable layer, but it is often enough to inspect default config files, package versions, or startup scripts.

Make the fix reproducible

Hand-editing a broken container can get you unstuck, but it should not become the permanent fix. Once you know what was wrong, move the change into:

• the Dockerfile
• an entrypoint script
• a mounted config file
• environment or orchestration settings

That way, the next container starts correctly without manual intervention.

Common Pitfalls

The most common mistake is editing the wrong location. A container may read configuration from a bind mount while you are repairing a copy inside the image filesystem that is never used.

Another issue is assuming docker exec can help with stopped containers. It cannot. Use docker cp, a helper container, or a debug image instead.

Permissions also matter. A copied file may be correct but unreadable to the process user inside the container. If startup still fails after the edit, check ownership and mode as well as content.

Finally, avoid treating docker commit as a long-term solution. A committed debug image is useful for investigation, but production fixes belong in versioned build or deployment configuration.

Summary

• First determine whether the broken file lives in a mount, volume, or container layer.
• Use docker cp for quick extraction and replacement of files in a stopped container.
• Use helper containers to inspect mounted volumes interactively.
• Create a temporary debug image when you need shell access to the stopped container’s writable layer.
• After diagnosing the issue, move the real fix into reproducible Docker configuration.