DocsICP FilingConsole
Documentation
Home Page Alibaba Cloud DevOps User Guide Flow FAQ Image build issues

Image build issues

Updated at:
Copy as MD
Product
My Favorites

This topic summarizes common image build issues and their solutions.

Slow pipeline builds from overseas images

  • Symptom: When you build an image in Alibaba Cloud DevOps, if your Dockerfile pulls an image from Docker Hub, such as:

    • FROM Nginx

    • FROM java:8

    • FROM openjdk:8-jdk-alpine

    Flow pulls the image from Docker Hub during the build. Network latency from connecting to overseas registries can make the build process extremely slow. A typical symptom appears in the Build and Push Image to Alibaba Cloud pipeline step: the build log shows that when executing FROM node:12.19.1, multiple file system (fs) layers remain in Pulling or Waiting status for a long time, significantly increasing the total build time.

  • Solution: Update your Dockerfile by following these steps:

    • Pull the overseas image to your local machine.

      docker pull openjdk:8-jdk-alpine

    • Push the base image to a repository in an Alibaba Cloud Container Registry (ACR) instance in a Chinese region, such as Beijing or Shanghai.

      docker tag openjdk:8-jdk-alpine registry.cn-beijing.aliyuncs.com/yournamespace/openjdk:8-jdk-alpine
docker push registry.cn-beijing.aliyuncs.com/yournamespace/openjdk:8-jdk-alpine

    • Modify the FROM instruction in your Dockerfile to pull the image from your image repository.

      from registry.cn-beijing.aliyuncs.com/yournamespace/openjdk:8-jdk-alpine

Build failure with Docker Hub base images

  • Symptom: The image build fails. A common cause is that the base image on Docker Hub has been updated.

  • Solution: Using maven:3-jdk-8 as an example, find the log from the most recent successful build and copy the sha256 digest value:

    [10:45:37] 3-jdk-8: Pulling from library/maven
[10:45:38] Digest: sha256:ff18d86faefa15d1445d0fa4874408cc96dec068eb3487a0fc6d07f359a24607
[10:45:38] Status: Image is up to date for maven:3-jdk-8

    In your Dockerfile, update the base image to maven:3-jdk-8@sha256:ff18d86faefa15d1445d0fa4874408cc96dec068eb3487a0fc6d07f359a24607.

Use a private image repository

What does "Use private image repository" in the build environment mean? Can I specify the container for the build?

The "Use private image repository" option lets you specify a custom image for your build environment instead of a default public one. Package your build environment into a Docker image and upload it to Alibaba Cloud Container Registry (ACR) or another private image repository. In the pipeline configuration, select "Use private image repository" and enter the full image address. This allows you to use a custom build environment for your builds.

In the build environment, select Specify Container Environment. For Container Image Address, click Enter Directly and provide the image address (for example, build-steps/alinux3). Then, select the Use private image repository checkbox and click Add Service Connection to configure the access credentials for your private repository.

Docker build hangs at the FROM instruction

This occurs when the build process cannot download the base image specified in the FROM instruction. To resolve this, pull the image to your local machine and then push it to a repository in Alibaba Cloud Container Registry (ACR) to accelerate image builds.

Permission error during a Docker build

Check if the image specified in the FROM instruction in your Dockerfile is a public image.

Cannot find files in COPY instruction

Ensure the file you are trying to copy exists and that its path relative to the build context is correct in your Dockerfile.

Build fails to clone code repository

Check if the code repository you are cloning is public. If it is a private repository, you must authorize access to it within your Dockerfile or base image.

Pipeline image build fails with 'failed to calculate checksum of ref xxxx: "xxx": not found'

Description

A pipeline image build fails at the COPY stage with the error failed to calculate checksum of ref xxxx, "xxx": not found.

Error example:

2025-06-19 19:03:07 [INFO] --------------------
2025-06-19 19:03:07 [INFO] 2 | 
2025-06-19 19:03:07 [INFO] 3 | RUN mkdir -p /usr/share/nginx/html/
2025-06-19 19:03:07 [INFO] 4 | >>> COPY dist/ /usr/share/nginx/html/
2025-06-19 19:03:07 [INFO] 5 | COPY cicd/nginx/production.conf /etc/nginx/conf.d/
2025-06-19 19:03:07 [INFO] 6 | COPY cicd/nginx/nginx.conf /etc/nginx/nginx.conf
2025-06-19 19:03:07 [INFO] --------------------
2025-06-19 19:03:07 [INFO] ERROR: failed to solve: failed to compute cache key: failed to calculate checksum of ref xxxxx::xxxxx: "/dist": not found

Troubleshooting

The error message and Step 3 of the error log indicate that the COPY command cannot find the source directory. In this example, the source directory is the dist directory.

  1. Verify the source path.

    To determine if a contextPath was specified during the build, check if the contextPath variable is set in the build steps, and then check if the source file exists by concatenating the base path with the path from the COPY command.

    • Specify contextPath at build time: The contextPath directory is used as the base path for the COPY operation.

    • If contextPath is not specified during a build, the directory of the Dockerfile is used as the base path for the COPY operation.

      The following figure shows an example where the contextPath variable is not specified:

      image

  2. Check for a .dockerignore file and its contents.

    The purpose of the .dockerignore file is to specify which files and directories to exclude from the Docker build context.

    During a build, if the system loads the .dockerignore file, the .dockerignore file may contain the source file path. This causes the path to be filtered out during the build, and a 'not found' error is reported even if the directory exists.

    The figure shows the .dockerignore file being loaded during the build process.

    image

Running apt-get update in an Alibaba Cloud DevOps image fails with 'bullseye-backports Release 404 Not Found'

Background

Solution for running apt-get update by using an Alibaba Cloud DevOps pipeline

image

Solution

This error occurs because the Debian image version is too old. The update command runs correctly on Debian 12. We recommend upgrading to a newer image.

1. The update command fails in a specified container environment

Option 1:

  1. Check Flow System Images and switch to an image with a newer Debian version. Follow these steps:

    1. In the build environment settings, find Container Image Address and click Enter Directly.

    2. Enter the address of the image you want to use.

    3. image

    4. image

Option 2:

Build your own base image with a newer Debian version, or install the required dependencies on the older Debian image. Then, use the resulting image in the pipeline (see steps a and b in Option 1).

Pass environment variables in pipeline builds

Option 1: Use the ARG instruction

In the Dockerfile, use ARG to receive build arguments and, as needed, use ENV to set them as runtime environment variables. When you build an image in a pipeline, pass the build arguments by setting the --build-arg flag. Dockerfile example:

FROM go-1.21-alpine 
ARG artifact
WORKDIR /root 
RUN echo "artifact:${artifact}" 
ENV artifact=${artifact}

Pipeline build argument configuration:

image

Option 2: Use file substitution

  1. Define a placeholder in the Dockerfile, such as ${ARTIFACT_NAME}.

  2. Set a variable in the pipeline (you can skip this step if you are using an existing pipeline variable).

  3. Before the image build step, add a Replace Environment Variables in File step to substitute the placeholder in the Dockerfile with the pipeline variable's value.

FROM go-1.21-alpine 
RUN echo "artifact:${artifact}" 
ENV artifact=${artifact}

image

Previous：Build issuesNext：Create a custom build environment