Container Registry's Image Builder automates image building from source code repositories using Dockerfiles. When a build fails, use this guide to identify the failure stage and apply the fix.
Identify your issue
Find your symptom in the table below and jump to the relevant section.
| Symptom | Section |
|---|---|
| Error binding a source code repository, or cannot find the Build tab | Failure to bind a source code repository |
| Cannot create an image building rule | Failure to create an image building rule |
| Webhook-triggered builds do not start | Failure to automatically build images |
| Builds are slow | Slow image building |
| Source code pull fails or times out | Failure to pull source code |
| Base image pull fails | Failure to pull images |
| Built image fails to push | Failure to push images |
| Build tasks stay in Pending state | Long Pending state for image building tasks |
| Build process fails with resource timeout | Failure in the process of building images |
Failure to bind a source code repository
To use Image Builder, bind an image repository to a source code repository first.
No permission to access the source code repository
Symptom: When you select a code source, an error message indicates that the source code account does not have access permissions.
Check whether the code source is already bound in Container Registry.
Source code repository not found
Symptom: After selecting a code source, the target repository does not appear in the list. This can occur for any of the following reasons:
-
No repositories listed — The network connection across regions is unstable. Enter the namespace and repository name directly in the fields instead of selecting from the list.
-
Project group repositories not supported — Container Registry does not support repositories belonging to project groups. Enter the namespace and repository name directly in the fields.
-
Repository not found in a long GitLab list — All public repositories are listed. Enter the namespace and repository name directly in the fields.
A Git repository URL supports only the two-level directory structure namespace/repository.git. Structures deeper than two levels are not supported.
Cannot find the Build tab
Symptom: After the image repository is created, the Build tab does not appear on the repository details page.
When you create an image repository and bind it to a source code repository, Container Registry performs these steps in sequence:
-
Creates the image repository.
-
Sends a request to your source code repository using the access token you specify, and sets a webhook.
-
Binds the image repository to the source code repository.
If the Build tab does not appear, check the following:
-
Refresh the Container Registry console and confirm the image repository was created.
-
Confirm the access token has permission to set webhooks in your source code repository.
-
Confirm the namespace and repository name in Container Registry match those in the Git repository URL exactly.
If all checks pass, you can find the Build tab on the image repository details page.
Failure to create an image building rule
Symptom: Creating a build rule fails with an error indicating the quota limit has been reached.
Apply for a quota increase to create more build rules.
Failure to automatically build images
Container Registry matches webhook requests from your source code platform against your build rules to trigger image builds. A build may fail to start for the following reasons:
-
Webhook was deleted — Set the webhook again in your source code repository.
-
Namespace or repository name changed — If you renamed your username or repository after binding, the webhook URL no longer matches. Roll back the username and repository name to the original values.
Slow image building
Unstable network connections across regions can slow down code pulling, image pulling, and resource downloads during a build.
For Container Registry Enterprise Edition instances:
-
Enable Intelligently Build Overseas Sources to accelerate builds using overseas sources.
-
If enabling this feature slows image pulling from a data center in the Chinese mainland, configure builds to pull images directly from that data center.
-
Combine both approaches to optimize builds from various sources.
For Container Registry Personal Edition instances:
-
Enable Build With Servers Deployed Outside Chinese Mainland to use overseas build servers.
-
Disable Build Without Cache to reuse cached layers and reduce download time.
Failure to pull source code
Source code repository not found or access denied
Symptom: The build log reports that the source code repository does not exist or is inaccessible.
If you changed the username of an Alibaba Cloud Code account after binding, source code cannot be pulled. To fix this:
-
Roll back the username to its original value.
-
Rebind the Alibaba Cloud Code account in Container Registry.
Source code pull times out
Symptom: The build log reports a timeout when pulling source code.
This is caused by an unstable network connection across regions. Enable Intelligently Build Overseas Sources to accelerate code pulling. See Slow image building.
Failure to pull images
Images from outside the Chinese mainland pull slowly
Symptom: The build fails to pull a base image from an image source outside the Chinese mainland.
Container Registry pulls base images from a Docker Hub mirror. If your Dockerfile references an image hosted by a cloud service provider outside the Chinese mainland, image pulling may slow down due to cross-region network issues. Use one of the following methods:
-
Upload the image to your Container Registry instance, then reference it directly from there.
-
Enable Build With Servers Deployed Outside Chinese Mainland.
Cannot pull images from a Personal Edition instance using the VPC endpoint
Symptom: The build fails to pull images from a Container Registry Personal Edition instance when using the virtual private cloud (VPC) endpoint.
Use the public endpoint of the Personal Edition instance for image building instead.
Cannot pull images from an Enterprise Edition instance using the public endpoint
Symptom: The build fails to pull images from a Container Registry Enterprise Edition instance when using the public endpoint.
Use the VPC endpoint of the Enterprise Edition instance for image building instead.
Failure to push images
Symptom: After the build succeeds, the image fails to push to the destination repository.
A Container Registry Personal Edition instance pushes the built image to the destination region over the Internet, so a cross-region network issue may cause the push to fail. If you build images on servers outside the Chinese mainland, the push to a region in the Chinese mainland may also fail for the same reason. Retry the push if it fails.
Long Pending state for image building tasks
Symptom: Build tasks remain in Pending state for an extended period.
Both Container Registry Personal Edition and Enterprise Edition limit the number of concurrent build tasks per user. If you have many queued tasks, use one of the following approaches:
-
Personal Edition — Upgrade to Container Registry Enterprise Edition to get a higher concurrent task limit.
-
Enterprise Edition — Apply for a quota increase for image building tasks.
Failure in the process of building images
Build process errors can have many causes. If the failure is related to resource download timeouts, accelerate image pulling. See Slow image building.