Fixing Docker's 'Not a Directory' Mount Error: A Practical Guide

The ErrorDocker deployments often grind to a halt when volume mounts go wrong. You might be using Docker Compose or mapping a simple nginx.conf file when this wall of text appears:

Error response from daemon: failed to create shim task: OCI runtime create failed: runc create failed: unable to start container process: error during container init: error mounting "/path/on/host/config.conf" to rootfs at "/etc/app/config.conf": mount through procfd: not a directory: unknown

This crash happens during the container's initialization. The OCI (Open Container Initiative) runtime, usually runc, is trying to bind-mount your host files, but it hit a structural mismatch it can't resolve.

The Root Cause: Structural MismatchesIt's a type conflict. Docker expected a file but found a folder, or vice versa. This usually stems from one of three common mistakes:

• The Missing Host File: If you mount /opt/app/settings.conf but that file doesn't exist yet, Docker (especially older versions) assumes you want a directory. It creates a folder named settings.conf/ on your host. When the container starts and expects a file, it fails.- Directory-to-File Conflict: You are trying to mount a host directory onto a path inside the container that the image already defined as a regular file.- File-to-Directory Conflict: You are trying to mount a single host file onto a container path that is actually a directory.The procfd reference is technical shorthand. It means the kernel's file descriptor traversal failed because a path component wasn't the directory it claimed to be.

Solution 1: Delete Accidental DirectoriesIf you ran docker compose up before actually creating your configuration file, Docker likely created a folder in its place. This is the #1 cause of this error.

First, verify the file type on your host:

ls -ld /path/to/your/host/config.conf

If the permissions string starts with d (like drwxr-xr-x), you have a directory where you need a file. Follow these steps to reset:

• Stop the failing container: docker compose down- Delete the incorrect directory: sudo rm -rf /path/to/your/host/config.conf- Create the file manually: touch /path/to/your/host/config.conf- Launch again: docker compose up -d## Solution 2: Audit the Container ImageSometimes the conflict lives inside the image itself. If a Dockerfile uses RUN touch /etc/app/config, that path is now a file. Trying to mount a host folder to that exact path will trigger the not a directory error. Peek inside the image to see what's actually there:

docker run --rm -it your-image-name ls -ld /etc/app/config

If the target is a directory, mount your file inside it instead: -v /host/path/config.conf:/etc/app/config/config.conf.

Solution 3: Use Absolute PathsRelative paths are convenient but risky. Docker's path resolution can be unpredictable depending on where the daemon is running. If you are using the CLI instead of Compose, always point to the full path.

Avoid this:

docker run -v ./nginx.conf:/etc/nginx/nginx.conf nginx

Use this instead:

docker run -v $(pwd)/nginx.conf:/etc/nginx/nginx.conf nginx

Solution 4: Check for Broken SymlinksDocker's procfd mechanism is sensitive to symlinks. If your host path points to a symbolic link, ensure the link isn't broken. A symlink pointing to a directory when Docker expects a file will crash the mount process immediately.

Check your link with ls -l /path/on/host/config.conf and confirm the destination exists and is the correct type.

VerificationAfter applying a fix, don't just hope it works. Verify it with these three steps:

• Start the Container: Ensure it moves past the OCI runtime error and reaches a running state.- Inspect Mounts: Run docker inspect <id>. In the "Mounts" section, confirm the "Source" and "Destination" look exactly as intended.- Test Access: Run docker exec -it <id> head -n 5 /path/in/container/config.conf to see the first 5 lines of your file from inside the container.## Prevention Tips- Pre-create your files: Use touch config.env or mkdir -p data before running Docker commands. Never let Docker guess.- Prefer Named Volumes: Unless you need to edit files in real-time on the host, use named volumes (e.g., -v app-data:/var/lib/app). They are more robust than bind mounts.- Explicit Dockerfiles: Use RUN mkdir -p /app/config in your Dockerfile to remove any ambiguity about your directory structure.