Skip to content

Container Startup Failure

Error message

                Error response from daemon: Container failed to start
              

Quick summary

The container exits immediately or fails to start, often due to a missing entrypoint, wrong command, or application crash on boot.

Why this happens

  • Missing or incorrect ENTRYPOINT/CMD in the Dockerfile

  • Application crashes on startup due to missing configuration or dependencies

  • The entrypoint script has a syntax error or references a missing file

  • The container's user lacks permission to execute the entrypoint

Minimal example

✗ Broken code
FROM node:18
COPY . .
CMD ["npm", "run", "prod"]  # script "prod" does not exist
✓ Fixed code
FROM node:18
COPY . .
CMD ["npm", "start"]  # correct script name

The broken code references a non-existent npm script. The fix uses the correct script name defined in package.json.

How to diagnose

  • Check container logs with docker logs <container> or kubectl logs <pod>

  • Run the image interactively to test: docker run -it --entrypoint /bin/sh <image>

  • Verify the ENTRYPOINT and CMD in the Dockerfile are correct

  • Check if the application starts successfully on your local machine

How to fix

  • Fix the ENTRYPOINT/CMD in the Dockerfile to point to the correct executable

  • Ensure all required configuration files and environment variables are provided

  • Add error logging at the start of your application to catch startup errors

  • Test the container locally before deploying to the cluster

How to prevent

  • Always test containers locally before pushing to production

  • Use a health check endpoint to verify startup success

  • Log startup steps so failures are easy to diagnose

Related Resources

Related Glossary

← Back to language