Resolving Docker Container Startup Failure: OCI Runtime Creation Error and Filesystem Permission Issues

Abstract: This article provides an in-depth analysis of the 'failed to create shim task: OCI runtime create failed' error encountered during Docker container startup, focusing on filesystem permission issues in Ubuntu environments. Through detailed examination of Docker Compose configurations, volume mounting mechanisms, and file permission settings, it offers comprehensive solutions and best practices. The article combines specific error cases to demonstrate how to resolve read-only file system errors by modifying Dockerfile with permission setup commands, and compares the effectiveness of multiple solution approaches.

Problem Background and Error Analysis

In Docker containerized deployment processes, developers frequently encounter container startup failures. This article provides a thorough analysis of the "failed to create shim task: OCI runtime create failed: runc create failed" error based on a typical Docker Compose deployment case in Ubuntu environment, examining root causes and solutions.

Error Symptoms and Diagnosis

When users execute the docker-compose -f docker-compose.yml -f docker-compose.dev.yml up -d --build command to start containers, although image building succeeds, severe errors occur during container startup phase. The error message clearly indicates: "error mounting to rootfs at \"/app/node_modules\": mkdir ... read-only file system: unknown".

From the error stack trace, several key pieces of information can be analyzed:

The error occurs during container initialization phase, involving filesystem mounting operations
The specific problem is failure when attempting to create the /app/node_modules directory
The underlying filesystem is recognized as read-only, preventing write operations

Configuration Analysis and Problem Identification

By analyzing the provided Docker Compose configuration files, we can identify the root cause in the volume mounting settings within the development environment configuration:

version: "3"
services:
  backend:
    volumes:
      - ./:/app:ro
      - /app/node_modules

There are two critical volume mounting configurations here:

./:/app:ro - Mounts the current directory as read-only to the container's /app directory
/app/node_modules - Creates an anonymous volume for the node_modules directory

The problem arises when Docker attempts to mount the anonymous volume to /app/node_modules. Since the parent directory /app has already been mounted as a read-only filesystem, it becomes impossible to create new subdirectories within that directory.

Solution Implementation

According to the best answer solution, we need to ensure that the /app/node_modules directory has correct ownership and permissions during the Dockerfile build phase. Here's the modified Dockerfile implementation:

FROM node:16-alpine
ENV NODE_ENV="development"
WORKDIR /app
COPY package.json .
COPY package-lock.json .
ARG NODE_ENV
RUN apk add g++ make py3-pip
RUN npm install
RUN chown -R node /app/node_modules
RUN npm install -g ts-node nodemon
COPY . ./
ENV PORT 8000
EXPOSE $PORT
CMD ["ts-node", "./src/server.ts"]

The key improvement is adding the RUN chown -R node /app/node_modules command. This command serves to:

Recursively modify ownership of the /app/node_modules directory and all its subfiles and subdirectories
Grant ownership to the node user, which is the default user in Node.js images
Ensure that during container runtime, the application has sufficient permissions to access and manipulate the node_modules directory

Technical Principles Deep Analysis

Linux Filesystem Permission Mechanism

In Linux systems, filesystem permission control is based on a user and group ownership model. When Docker containers start, processes within the container run with specific user identities. If these users lack sufficient permissions for directories they need to access, operations will fail.

In Alpine Linux base images, applications typically run with non-root users by default to enhance security. This requires pre-configuring directory permissions during the build phase to ensure runtime users can properly access required resources.

Docker Volume Mounting Mechanism

Docker's volume mounting mechanism involves complex filesystem overlaying:

When mounting host directories to containers, Docker creates overlay filesystems
Read-only mounts restrict write operations to that directory within the container
Anonymous volume mounting requires write permissions at the target path
Permission conflicts lead to container initialization failures

OCI Runtime and runc

The OCI (Open Container Initiative) runtime specification defines standard interfaces for container execution. runc, as the OCI reference implementation, manages container lifecycle. When runc encounters filesystem permission issues while creating container processes, it throws the runtime creation error discussed in this article.

Alternative Solutions Comparison

Permission Modification Approach (Score 6.5)

Some suggestions propose using chmod +x ./src/server.ts to modify file execution permissions. This method works for resolving executable file permission issues but has limited effectiveness for directory creation and filesystem mounting problems.

Container Cleanup Approach (Score 4.7)

Simple docker-compose down && docker-compose up -d commands might be effective for cache or state-related issues in some cases, but cannot provide lasting solutions for fundamental permission configuration problems.

Timeout Adjustment Approach (Score 10.0)

Setting COMPOSE_HTTP_TIMEOUT=480 and performing container cleanup operations can resolve temporary issues caused by network timeouts or resource competition, but needs to be combined with specific permission fixes.

Best Practices and Preventive Measures

Dockerfile Design Principles

Pre-configure required directory permissions during build phase
Run applications with non-root users to enhance security
Arrange COPY and RUN command sequences properly to avoid unnecessary layer rebuilding
Configure volume mounting strategies appropriately in development environments

Development Environment Configuration Recommendations

Carefully plan read-write permission configurations for volume mounts
Avoid creating sub-volumes requiring write permissions under read-only mounted directories
Use named volumes instead of anonymous volumes for easier management and debugging
Regularly clean up unused container, image, and volume resources

Conclusion

This article provides a detailed analysis of OCI runtime creation failure errors encountered during Docker container startup processes, focusing on resolving read-only file system issues caused by improper filesystem permission configurations. By modifying Dockerfile with appropriate permission setup commands, these Linux-environment-specific permission problems can be effectively resolved. The article also offers comparative analysis of multiple solution approaches, helping developers choose the most suitable resolution method based on specific scenarios.

In practical development, understanding Docker's filesystem mechanisms, permission models, and volume mounting principles is crucial for avoiding similar issues. By following best practices and reasonable configuration strategies, the stability and maintainability of containerized applications can be significantly improved.

Copyright Notice: All rights in this article are reserved by the operators of DevGex. Reasonable sharing and citation are welcome; any reproduction, excerpting, or re-publication without prior permission is prohibited.