Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

sam local fails: Running AWS SAM projects locally requires Docker

ErrorError: Running AWS SAM projects locally requires Docker. Have you got it installed?

Short answer

sam local start-api and sam local invoke run your function inside a Docker container, so SAM stops if it cannot talk to Docker. Check that docker ps works for your user. If the command is missing, install Docker. If the daemon is stopped, start it. If you get a permission error, add your user to the docker group.

  • Applies to AWS SAM CLI 1.x, Docker Engine, Ubuntu 24.04, Amazon Linux 2023
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Run the one command SAM itself relies on. Its result tells you which cause applies: command not found means Docker is not installed, a daemon message means it is not running, a permission message means your user cannot use the socket.

    docker ps
  2. 2Match what you see, then jump to its fix

    1. 1docker: command not foundDocker is not installedFix
    2. 2Cannot connect to the Docker daemon. Is the docker daemon running on this host?Docker is installed but the daemon is not runningFix
    3. 3docker ps works with sudo but fails without it, or the daemon error appears only for your userYour Linux user is not allowed to use the Docker socketFix

What does the error look like?

  • Error: Running AWS SAM projects locally requires Docker. Have you got it installed?
  • Cannot connect to the Docker daemon. Is the docker daemon running on this host?

Cause 1 of 3

Docker is not installed

1Check

Docker is only needed for local testing and for sam build --use-container, so a machine set up just to deploy may not have it.

docker --version

2Fix

Install Docker for your system (the SAM guide points to the Docker site for Ubuntu, Debian and CentOS). On Amazon Linux 2023 the SAM guide installs the docker package with yum.

sudo yum install -y docker

3Verify

docker ps prints a header line, even with no containers.

docker ps

Confirmed by docs.aws.amazon.com

Did this fix it?

Cause 2 of 3

Docker is installed but the daemon is not running

1Check

The client is there, but nothing is listening on the Docker socket. On a laptop that usually means Docker Desktop was not started.

docker ps

2Fix

Start the service. On Linux use the service command from the SAM guide, and enable it so it starts after a reboot. On macOS or Windows, open Docker Desktop and wait until it reports running.

sudo service docker start
sudo systemctl enable docker.service

3Verify

docker ps answers without a daemon error.

docker ps

Confirmed by docs.aws.amazon.com

Did this fix it?

Cause 3 of 3

Your Linux user is not allowed to use the Docker socket

1Check

Only root and members of the docker group may talk to the daemon. The SAM guide adds the user to that group and says the new membership only applies to a new login session.

id -nG | tr ' ' '\n' | grep -x docker

2Fix

Add your user to the docker group, then log out and in again (or run newgrp docker in the current shell).

sudo usermod -aG docker $USER
newgrp docker

3Verify

docker ps works without sudo, then sam local works.

docker ps
sam local invoke

Confirmed by docs.docker.com

Did this fix it?

How do I stop it coming back?

  • Add docker ps to your project setup notes so new team members check Docker before the first sam local run.
  • Enable the Docker service at boot on build machines.
  • On CI runners that only deploy, skip local invocations instead of installing Docker.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Servers

Apache has a certificate, but https:// does not open

No line with :443 in the output of ss -ltnp

HTTPS needs four things at once: mod_ssl loaded, Apache listening on 443, a virtual host on 443 with SSLEngine on, and a firewall that lets 443 in.

4 causes, each with a fix

Servers

AWS CLI says you must specify a region

You must specify a region. You can also configure your region by running "aws configure".

The AWS CLI sends every request to one region and has none to use.

4 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.