After nearly a year of happily using Amplify Gen2, I started facing problems as soon as I added a Docker image asset to my project.

I had something along these lines:

const cluster = new ecs.Cluster(stack, 'ECSCluster', {
  clusterName: 'ECSCluster',
  vpc: vpc,
});

const taskDefinition = new ecs.FargateTaskDefinition(stack, 'TaskDefinition', {
  cpu: 4096,
  memoryLimitMiB: 16384,
  runtimePlatform: {
    cpuArchitecture: ecs.CpuArchitecture.X86_64,
    operatingSystemFamily: ecs.OperatingSystemFamily.LINUX,
  },
})

const dockerImageAsset = new DockerImageAsset(stack, 'DockerImageAsset', {
  directory: resolvePath('./docker'),
  platform: Platform.LINUX_AMD64,
});
// see https://aws.amazon.com/blogs/aws/aws-fargate-enables-faster-container-startup-using-seekable-oci/
// and https://github.com/aws/aws-cdk/issues/26413
SociIndexBuild.fromDockerImageAsset(stack, 'Index', imageProcessorDockerImage);

taskDefinition.addContainer('Container', {
  containerName: 'Container',
  image: ecs.ContainerImage.fromDockerImageAsset(imageProcessorDockerImage),
  essential: true,
});

As soon as I added this to my Amplify Gen2 + CDK project, my build started to fail without any clear error message:

2025-04-27T08:46:25.054Z [INFO]: 8:46:25 AM Building and publishing assets...
2025-04-27T08:46:26.340Z [INFO]: 
2025-04-27T08:46:26.341Z [WARNING]: ampx pipeline-deploy
                                    Command to deploy backends in a custom CI/CD pipeline. This command is not inten
                                    ded to be used locally.
                                    Options:
                                    --debug            Print debug logs to the console
                                    [boolean] [default: false]
                                    --branch           Name of the git branch being deployed
                                    [string] [required]
                                    --app-id           The app id of the target Amplify app[string] [required]
                                    --outputs-out-dir  A path to directory where amplify_outputs is written. I
                                    f not provided defaults to current process working dire
                                    ctory.                                         [string]
                                    --outputs-version  Version of the configuration. Version 0 represents clas
                                    sic amplify-cli config file amplify-configuration and 1
                                    represents newer config file amplify_outputs
                                    [string] [choices: "0", "1", "1.1", "1.2", "1.3", "1.4"] [default: "1.4"]
                                    --outputs-format   amplify_outputs file format
                                    [string] [choices: "mjs", "json", "json-mobile", "ts", "dart"]
                                    -h, --help             Show help                                     [boolean]
2025-04-27T08:46:26.341Z [INFO]: 
2025-04-27T08:46:26.342Z [INFO]: [CDKAssetPublishError] CDK failed to publish assets
                                  ∟ Caused by: [_ToolkitError] Failed to publish asset data Nested Stack Template (current_account-current_region)
                                  Resolution: Check the error message for more details.
2025-04-27T08:46:26.342Z [INFO]: 
2025-04-27T08:46:26.343Z [INFO]: 
2025-04-27T08:46:26.345Z [INFO]:

Appending a debug flag to the amplify deploy command helped to identify Docker was not available in the path, although hidden through an INFO message somewhere in the middle of the logs.

version: 1
backend:
  phases:
    build:
      commands:
        - npm i
        - npx ampx pipeline-deploy --branch $AWS_BRANCH --app-id $AWS_APP_ID --debug
frontend:
  phases:
    build:
      commands:
        - npm run build
  artifacts:
    baseDirectory: dist
    files:
      - '**/*'
  cache:
    paths:
      - .npm/**/*
      - node_modules/**/*
2025-04-27T10:15:35.435Z [INFO]: 10:15:35 AM [deploy: CDK_TOOLKIT_E0000] 10:15:35 AM amplify-main-branch: fail: Unable to execute 'docker' in order to build a container asset. Please install 'docker' and try again.

In this case, we need to use a different image compatible with AWS CodeBuild. A list of official AWS CodeBuild curated Docker images can be found here.

By scrolling down in the Hosting/Build settings area, it is possible to set a custom image, such as public.ecr.aws/codebuild/amazonlinux-x86_64-standard:5.0, *which contains Docker.*

Using custom image in build settings

After switching to the image mentioned above, it is still necessary to start dockerd by running the /usr/local/bin/dockerd-entrypoint.sh script before building with Docker in your amplify.yml, like the example below:

version: 1
backend:
  phases:
    build:
      commands:
        - /usr/local/bin/dockerd-entrypoint.sh      
        - npm i
        - npx ampx pipeline-deploy --branch $AWS_BRANCH --app-id $AWS_APP_ID --debug
frontend:
  phases:
    build:
      commands:
        - npm run build
  artifacts:
    baseDirectory: dist
    files:
      - '**/*'
  cache:
    paths:
      - .npm/**/*
      - node_modules/**/*

And voilà! Your project should now be able to build the Docker image successfully.

Thanks for reading! Do you have any cool ideas or feedback you'd like to share? Please drop a comment, send me a message, or follow me, and let’s keep building!