sam local fails: Running AWS SAM projects locally requires Docker
Error: 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.
Fix it fast
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 ps2Match what you see, then jump to its fix
- 1
docker: command not foundDocker is not installedFix - 2
Cannot connect to the Docker daemon. Is the docker daemon running on this host?Docker is installed but the daemon is not runningFix - 3
docker 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
- 1
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 --version2Fix
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 docker3Verify
docker ps prints a header line, even with no containers.
docker psConfirmed by docs.aws.amazon.com
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 ps2Fix
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.service3Verify
docker ps answers without a daemon error.
docker psConfirmed by docs.aws.amazon.com
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 docker2Fix
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 docker3Verify
docker ps works without sudo, then sam local works.
docker ps
sam local invokeConfirmed by docs.docker.com
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:
- Dispatch ProA real-time logistics platform: Flutter apps, Spring Boot services and a Kafka event pipeline on AWS.
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- RaheebA consumer app shipped to both stores from one Flutter codebase on a .NET and Azure back end.
Related fixes
Servers
Apache logs SIGWINCH and exits on its own
the httpd container stops although nothing crashed
SIGWINCH is Apache's graceful-stop signal.
2 causes, each with a fixServers
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 fixServers
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 fixServers
docker login to Amazon ECR fails with: Cannot perform an interactive login from a non TTY device
Cannot perform an interactive login from a non TTY device
Docker asked for a password because none reached it, and a pipe or script has no keyboard to answer.
3 causes, each with a fixServers
The Java SDK finds no AWS credentials on an EC2 instance or in a container on it
InstanceProfileCredentialsProvider()
The SDK walks a fixed list of credential sources and the EC2 instance role is the last one.
3 causes, each with a fixServers
cdk deploy fails in a GitLab job with spawnSync docker ENOENT
code: 'ENOENT'
ENOENT means the operating system found no docker program to run.
3 causes, each with a fix