Maaz Zindani

Loading the index…

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

cdk deploy fails in a GitLab job with spawnSync docker ENOENT

ErrorError: spawnSync docker ENOENT

Short 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.

  • Applies to AWS CDK v2, GitLab CI Docker executor, Node.js 22
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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 info
  2. 2Match what you see, then jump to its fix

    1. 1command -v docker prints nothingThe job image has no Docker client, or no Docker daemon behind itFix
    2. 2The failure appears while bundling a NodejsFunction, and the stack has no Docker image assetsNodejsFunction falls back to Docker because esbuild is not installedFix
    3. 3docker 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

What does the error look like?

  • Error: spawnSync docker ENOENT
  • code: '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.yml

2Fix

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 never

3Verify

docker info prints server details, and cdk deploy gets past the build step.

docker info | head -5

Confirmed by docs.gitlab.com

Did this fix it?

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 esbuild

2Fix

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@0

3Verify

Synthesize again; it should no longer call docker.

npx cdk synth

Confirmed by docs.aws.amazon.com

Did this fix it?

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 info

2Fix

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-runner

3Verify

The same docker info command now prints server details.

sudo -u gitlab-runner -H docker info

Confirmed by docs.gitlab.com

Did this fix it?

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:

Related fixes

Next step

Want this handled for good?

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