How to troubleshoot exit code 1 in Docker

Nobody likes to see errors, but they’re inherent in all software programs. Issues may pop up, whether you’re running simple scripts or managing large-scale apps.

Docker uses exit codes to propagate errors in processes. exit code 1 is one of the most common and frustrating errors for developers. Let’s explore what it means and how to fix it.

What is exit code 1 in Docker?

exit code 1 is the error code for signaling that a container’s process has been terminated due to a general or unspecified error.

When you execute processes in your Docker containers, you may have noticed an exit code 0, which means your process was successful. In other cases where your container terminates, you’ll get an exit code 1.

When your container processes terminate with an exit code, the code indicates the process’s status (failed or completed).

exit code 1 is usually a general error or failure. If you’re using Docker, a process has either failed or there’s a general error. You must pinpoint which is best and solve the underlying issue.

Some of the common reasons you’ll get an exit code 1 error are:

• Process execution failure — The primary process in your container, e.g. apps and scripts, may fail, and if you’ve not adequately handled exceptions, you’ll get an exit code 1 from the container
• Missing dependencies — Missing and failing dependencies like files, libraries, and environment variables might be one reason you get an exit code 1
• Incorrect ENTRYPOINT or CMD — The entry point or command is invalid in the container specifications file
• Resource constraints — The container you’ve provisioned might have memory or CPU constraints that make it impossible to complete the process you’re running.
• Network issues — When containers have connectivity issues like database connection errors and external service issues, you can export the mistake to cause an exit code 1
• Permission issues — The user executing the processes in your container might not have sufficient permissions to manage processes in the container

Let’s reproduce exit code 1 with this scenario so you can understand how it happens.

First, create a bash script and name it failing.sh, then add these commands:

#!/bin/bash
echo "This script will fail with Exit Code 1."
exit 1

Now, execute this command to make the script executable:

chmod +x failing.sh

Next, create a Dockerfile in the same directory and enter these directives.

# Use a lightweight base image
FROM alpine:latest

# Copy the failing script into the container
COPY failing.sh /failing.sh

# Set the script as the default command
CMD ["/failing.sh"]

The Dockerfile copies the script into the container and runs it as the default command.

Finally, run the build command to build the container:

docker build -t exit-code-1-demo .

If you’ve done everything right, you should get a resounding error with exit code 1:

The error arises because the failing.sh script explicitly exists with exit code 1 signaling a failure. When the container starts, it executes the script as the default comm2 and terminates with a non-zero exit.

Since Docker treats non-zero exit codes as failures, it reports the failure accordingly.

In this case, we’ve simulated a process failure, but in development, yours will be real, and you’ll need to troubleshoot.

How to troubleshoot containers with exit code 1

Once you’ve received an error with exit code 1, you want to troubleshoot it and find the root cause to get your app running. Here are some practices you can follow to troubleshoot the errors.

Inspect the container state

You should inspect the container’s state with the ps command to gather more information about its lifecycle, especially why it might have terminated:

docker ps -a

The command lists all containers, including the exited ones. To troubleshoot, look for the specific container’s status and exit code.

Check logs

When you receive an error, you should first check your logs. Sometimes, you’ll find intuitive logs about the error that could help you resolve it:

docker logs <container_id>

The command should display the output and error messages from the container. Then, you can look for error messages, stack traces, missing files or dependencies, and permission errors.

Check the container ENTRYPOINT and CMD

Another way to get an exit code 1 is to miss the correct entry point or command. You might have specified incorrect paths to scripts or executables, or had missing or invalid arguments.

Check the CMD or ENTRYPOINT directives in your Dockerfile and make sure they’re valid.

CMD ["/failing.sh"] 

In this case, the CMD directive is the same as the example we used to reproduce the exit code 1 error. However, it’s valid.

Verify dependencies and environment variables

You need to make sure you’re installing all the dependencies your project requires to run.

You can use the exec command to inspect the container’s file system and browse through to further check for missing files and dependencies:

docker exec -it <container_id> /bin/sh|

Also, make sure you’re passing the right environment variables. You can use the COPY directive or specify the environment variable in your Docker Compose file.

Solutions for handling exit code 1

Let’s overview some fixes for exit code 1 to get you deploying your apps on the fly:

Fixing application errors in the container

Application errors are one of the common causes of exit code 1. You can easily fix them by debugging your apps and handling exceptions.

Log at different levels during development to capture detailed messages and handle exceptions to prevent crashes.

Make sure you test locally before containerizing to pinpoint where the problem originates. If you don’t have any errors testing locally, then it’s probably from the container. You’ll want to spin up a container with configurations identical to your local environment.

Fixing environment variable issues

Your deployment will likely fail if you misplace the environment variables it needs to run.

You can check your Docker container’s environment variables with the inspect command:

docker inspect <container_id> --format '{{ .Config.Env }}'

Make sure you’re specifying the environment variables in your Dockerfile with the ENV directive:

ENV MY_VAR=my_value

Also, consider providing default values for environment variables in your app’s implementation and handle their exceptions gracefully.

Check for resource limitations

Resource constraints as your project grows may result in an error with exit code 1.

You can use docker stats to monitor the resource usage of your container like this:

docker stats <container_id>

You can go further to adjust memory and resource limits with:

docker run --memory="512m" --cpus="1" my-image

In this case, the command runs a Docker container from my-image, limiting memory usage to 512MB and CPU usage to 1 core.

Debugging failed dependencies

If the issue is a failed dependency, you can always interact with the container to find and fix the issues. The Docker exec command is great in this regard:

docker exec -it <container_id> /bin/sh
ls -l /path/to/dependency

You can rebuild with the build command once you’ve found and fixed the issues.

Automating container behavior with restart policies

Gracefully, Docker provides restart policies for you to specify what happens when your container’s processes fail.

You can configure restart policies so your container recovers from failures in your Docker Compose YAML file:

Policy	Execution
no	The container won’t restart (default)
always	The container always restarts regardless of the exit code
on-failure	The container restarts on non-zero exit codes like exit code 1
unless-stopped	The container would always restart except it’s explicitly stopped

Here’s how you can specify the restart policy in your docker-compose.yml file:

version: '3.8'
services:
  my-service:
    image: my-image


    # use any one of these
    restart: "no"
    restart: "always"
    restart: "on-failure"
    restart: "on-failure:5"  # Retry up to 5 times
    restart: "unless-stopped"

You can do this for any of the services you’re orchestrating via Docker Compose, and it should work as expected.

Conclusion

In this article, you’ve learned what causes errors with exit code 1 and how you can mitigate them in your development and deployment processes.

In production and staging, use these restart policies to make sure your app is always available for your users.