cdk deploy fails in a GitLab job with spawnSync docker ENOENT
Error: spawnSync docker ENOENTShort answer
ENOENT means the operating system found no docker program to run. CDK calls docker to build image assets and to bundle some Lambda code, and your GitLab job image has no Docker client. Use a job image with the Docker CLI plus a docker:dind service, or install esbuild so NodejsFunction does not need Docker.
Fix it fast
1Find out which cause you have
Run these two commands as the first lines of the failing job. If the first prints nothing, the image has no Docker client.
command -v docker docker info2Match what you see, then jump to its fix
- 1
command -v docker prints nothingThe job image has no Docker client, or no Docker daemon behind itFix - 2
The failure appears while bundling a NodejsFunction, and the stack has no Docker image assetsNodejsFunction falls back to Docker because esbuild is not installedFix - 3
docker is installed on the host, but the job still cannot run itThe job runs on a shell executor where the runner user cannot use DockerFix
- 1
What does the error look like?
Error: spawnSync docker ENOENTcode: 'ENOENT'
Cause 1 of 3
The job image has no Docker client, or no Docker daemon behind it
1Check
A GitLab Docker-executor job runs only inside the image you name, so tools missing from that image are missing in the job. CDK builds Docker image assets locally, which needs both the CLI and a daemon.
# .gitlab-ci.yml: look at the job's image and services
grep -n -E 'image:|services:' .gitlab-ci.yml2Fix
Use an image that contains the Docker CLI and add the docker:dind service. dind requires a runner with privileged mode. If the image also needs Node.js for cdk, build one image that has both.
deploy:
image: my-registry/cdk-with-docker:latest
services:
- docker:24.0.5-dind
variables:
DOCKER_TLS_CERTDIR: "/certs"
before_script:
- docker info
script:
- npx cdk deploy --require-approval never3Verify
docker info prints server details, and cdk deploy gets past the build step.
docker info | head -5Confirmed by docs.gitlab.com
Cause 2 of 3
NodejsFunction falls back to Docker because esbuild is not installed
1Check
The CDK docs say esbuild is used locally if available; otherwise bundling happens in a Docker container.
npm ls esbuild2Fix
Add esbuild as a dev dependency of the project that runs cdk (in a monorepo, the root package.json), so no container is needed.
npm install --save-dev esbuild@03Verify
Synthesize again; it should no longer call docker.
npx cdk synthConfirmed by docs.aws.amazon.com
Cause 3 of 3
The job runs on a shell executor where the runner user cannot use Docker
1Check
On the shell executor, GitLab documents that the gitlab-runner user needs Docker access. Test it as that user.
sudo -u gitlab-runner -H docker info2Fix
Follow GitLab's shell-executor setup so the runner user is allowed to use Docker. This gives that user root-level power on the host, so use it only on a dedicated runner.
sudo usermod -aG docker gitlab-runner3Verify
The same docker info command now prints server details.
sudo -u gitlab-runner -H docker infoConfirmed by docs.gitlab.com
How do I stop it coming back?
- Put docker info at the top of every job that deploys with CDK, so a missing Docker fails in one line.
- Prefer esbuild local bundling for Lambda code so most deploys need no Docker.
- Keep one pinned CI image with Node.js, the CDK and the Docker CLI, instead of installing tools on every run.
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:
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- Dispatch ProA real-time logistics platform: Flutter apps, Spring Boot services and a Kafka event pipeline on AWS.
- WorkforceA field app, an admin console and a self-hosted Node.js server for push and reconciliation.
Related fixes
Servers
ng serve runs in the container but localhost:4200 does not open
The browser cannot open localhost:4200 although ng serve is running in the container
ng serve listens on localhost by default, which inside a container is the container itself.
3 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
sam local fails: Running AWS SAM projects locally requires Docker
Cannot connect to the Docker daemon. Is the docker daemon running on this host?
sam local start-api and sam local invoke run your function inside a Docker container, so SAM stops if it cannot talk to Docker.
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
bcrypt_lib.node: invalid ELF header inside a Docker container
Error: /app/node_modules/bcrypt/lib/binding/napi-v3/bcrypt_lib.node: invalid ELF header
bcrypt is a compiled addon, so the file in node_modules only runs on the operating system it was installed on.
3 causes, each with a fixServers
AWS CDK cannot find module '@aws-cdk/aws-ec2' (or another @aws-cdk/aws-* package)
Cannot find module '@aws-cdk/aws-ec2'
CDK v2 no longer ships one npm package per service.
3 causes, each with a fix