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 page | 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 GitLab
Symptom: When selecting a code source, an error states that the account has no permission to access GitLab.
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.
If the repository URL is invalid, make sure it uses a two-level directory structure: namespace/repository.git.
Cannot find the Build page
Symptom: After creating an image repository, the Build page does not appear in the left-side navigation pane.
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 page 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, go to the image repository details page, then click Build in the left-side navigation pane. 
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
Image builds triggered by webhook requests from your source code platform can fail 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: Base images from Docker Hub or a cloud provider outside the Chinese mainland may pull slowly due to an unstable network connection across regions.
Container Registry uses images from Docker Hub. If you use an image from a cloud service provider outside China, the speed of image pulling may be slow. Use either of the following approaches:
-
Upload the image to your Container Registry instance, then reference it directly from there.
-
Enable Intelligently Build Overseas Sources.
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 a successful build, the image fails to push to a repository in the Chinese mainland.
This occurs when Build With Servers Deployed Outside Chinese Mainland is enabled on a Container Registry Personal Edition instance, and the cross-region push fails due to network instability. Retry the push, or disable Build With Servers Deployed Outside Chinese Mainland.
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.