How to fix Container exited with status code 2 in Docker

DockerBEGINNERMEDIUMUpdated Dec 6, 2025· 317 views

Exit code 2 in Docker indicates a misuse of a shell command or invalid arguments passed to a command inside the container. This is a standard Unix/Linux convention where code 2 typically signals command syntax errors, missing required arguments, or incorrect usage of shell builtins.

Quick fix

Fixes Container exited with status code 2

docker logs <container_name_or_id>
  1. Check container logs for the exact error
  2. Run an interactive shell to debug
  3. Verify files exist at expected paths
  4. Fix shell script syntax errors
docker — error
docker logs <container_name_or_id>
Container exited with status code 2

What this error means

Exit code 2 is a Unix/Linux convention that typically means "misuse of shell builtins" or command syntax errors. Unlike Docker-specific exit codes (125, 126, 127), exit code 2 comes from the command running inside your container, not from Docker itself. When your container exits with code 2, it usually means the command or script executed inside the container received invalid arguments, encountered a syntax error, or was called incorrectly. Many command-line tools use exit code 2 specifically to indicate usage errors or invalid options. Common examples include: bash returning 2 for syntax errors, grep returning 2 for invalid options, and many CLI tools using 2 to signal incorrect command invocation. The error originates from the application layer, so you need to examine what command failed and why.

Typical symptoms

  • Container exits immediately after starting with exit code 2
  • docker logs shows syntax errors or usage messages
  • Error messages like 'missing ]' or 'unexpected token'
  • Commands work locally but fail in container
  • Shell scripts fail with 'syntax error' messages
  • docker-compose services exit with code 2
  • CI/CD pipeline fails at container execution stage

Common causes

  1. Shell syntax errors in scripts (missing quotes, brackets, or keywords)
  2. Invalid arguments or options passed to a command
  3. Missing required files or scripts referenced in CMD/ENTRYPOINT
  4. WORKDIR pointing to wrong directory so scripts cannot be found
  5. Volume mounts overwriting directories containing required files
  6. Windows line endings (CRLF) causing shell parsing errors
  7. JSON array CMD being incorrectly parsed as shell command
  8. Environment variables not set or expanded incorrectly
  9. Incorrect shebang line in shell scripts

How to fix "Container exited with status code 2"

1Check container logs for the exact error

First, examine the container logs to see what command failed and why:

bash
docker logs <container_name_or_id>

Look for error messages like "syntax error", "missing argument", "invalid option", or usage help text that indicates incorrect command invocation.

2Run an interactive shell to debug

Start the container with an interactive shell to manually test commands:

bash
docker run -it --entrypoint /bin/sh <image_name>

Once inside, try running the commands from your Dockerfile or entrypoint script manually to identify which one fails.

3Verify files exist at expected paths

A common cause is missing files. Check that your scripts and referenced files exist:

bash
# Inside the container
ls -la /app/
cat /app/entrypoint.sh

If using WORKDIR, ensure the directory exists and contains your files. Volume mounts can overwrite directories, hiding files copied during build.

4Fix shell script syntax errors

Validate your shell scripts for syntax errors before building:

bash
# Check bash script syntax
bash -n your-script.sh

# Check sh script syntax
sh -n your-script.sh

Common issues include:
- Missing closing brackets in conditionals: [ -f file ] not [ -f file
- Unclosed quotes or missing spaces around brackets
- Using bash-specific syntax in /bin/sh scripts

5Check CMD/ENTRYPOINT format

Ensure your Dockerfile uses the correct format for CMD and ENTRYPOINT:

dockerfile
# Exec form (recommended) - runs command directly
CMD ["python", "app.py"]

# Shell form - runs through /bin/sh -c
CMD python app.py

If using exec form, ensure it's valid JSON. A malformed array like CMD ["python" "app.py"] (missing comma) will cause parsing errors.

6Fix Windows line endings

If developing on Windows, shell scripts may have CRLF line endings that cause parsing errors:

bash
# Convert to Unix line endings
dos2unix your-script.sh

# Or in Dockerfile
RUN sed -i 's/\r$//' /app/entrypoint.sh

You can also configure Git to handle line endings:

bash
git config --global core.autocrlf input
7Debug with shell tracing

Enable verbose output to see exactly which command fails:

dockerfile
# Temporarily add -x flag for debugging
CMD ["/bin/sh", "-x", "/app/entrypoint.sh"]

Or add set -x at the top of your shell script. This prints each command before execution, making it easy to identify the failing line.

8Verify environment variables

Commands may fail if required environment variables are missing:

bash
# Check environment in container
docker run --rm <image_name> env

# Or inspect a running container
docker exec <container_id> env

Ensure variables referenced in scripts are defined in your Dockerfile or docker-compose.yml.

Advanced notes

Understanding exit codes: Exit code 2 is not Docker-specific. Docker only defines codes 125 (daemon error), 126 (command cannot execute), and 127 (command not found). Code 2 comes from the command inside your container.

grep and diff special cases: Some tools have specific meanings for exit code 2. For example, grep returns 2 for errors (vs 1 for "no match"), and diff returns 2 for trouble (vs 1 for "files differ").

Docker Compose exit codes: When using docker-compose up --exit-code-from <service>, the compose command returns the exit code of the specified service. Exit code 2 from compose itself may indicate configuration issues.

Debugging crashed containers: If the container exits too quickly, override the entrypoint:

bash
docker run -it --entrypoint /bin/sh <image_name> -c "sleep infinity"

Then exec into it to debug.

Multi-stage builds: Ensure scripts copied from builder stages have correct permissions and line endings. Use chmod +x and consider running dos2unix in the Dockerfile.

Frequently asked questions

What does "Container exited with status code 2" mean?
Exit code 2 is a Unix/Linux convention that typically means "misuse of shell builtins" or command syntax errors. Unlike Docker-specific exit codes (125, 126, 127), exit code 2 comes from the command running inside your container, not from Docker itself. When your container exits with code 2, it usually means the command or script executed inside the container received invalid arguments, encountered a syntax error, or was called incorrectly.
How do I fix "Container exited with status code 2"?
Exit code 2 in Docker indicates a misuse of a shell command or invalid arguments passed to a command inside the container. This is a standard Unix/Linux convention where code 2 typically signals command syntax errors, missing required arguments, or incorrect usage of shell builtins.
What causes "Container exited with status code 2"?
Shell syntax errors in scripts (missing quotes, brackets, or keywords) Invalid arguments or options passed to a command Missing required files or scripts referenced in CMD/ENTRYPOINT
Is the "Container exited with status code 2" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading