Image Build Diagnostics & AI Root Cause Analysis Overview - Container Registry

When an image build fails, the error output often points to a symptom rather than the underlying cause. Build diagnostics analyzes your build tasks to surface root causes, flag potential risks, and identify optimization opportunities—combining expert rules with the Tongyi Qianwen large language model (LLM) to generate targeted repair suggestions.

Important

When you use build diagnostics, Alibaba Cloud collects data from your container image repositories, including repository information, build configuration, build task logs, and build history. Do not store sensitive data in build configurations or output sensitive data to build logs. For details, see Usage notes.

How it works

Build diagnostics runs in three stages:

Data pre-processing: Collects instance status, repository configuration, build rules, and build logs to detect exceptions quickly.
Rule detection: Analyzes the collected data for exceptions, potential risks, and optimization opportunities.
Root cause analysis: Uses the collected data and detection results to identify the root cause of each problem and generate repair suggestions.

The diagnosis results fall into two categories:

Items to be fixed: Root causes of exceptions, repair suggestions, and exception location details.
AI diagnosis: In-depth analysis of build instructions or configuration items, with comprehensive optimization suggestions generated by the LLM.

Run build diagnostics

On the Image Build Diagnostics page, click Diagnostics. In the Select Image Build Task panel, select the build task to diagnose:
- Namespaces: The namespace the build task belongs to.
- Image Repositories: The repository the build task belongs to.
- Image Build Task ID: The ID of the build task.
Read the usage notes, select I understand and agree, and then click Initiate Diagnostics.
After the diagnosis completes, review the results and apply the repair suggestions. Use the diagnostic rules reference below to understand each finding.

Diagnostic rules reference

The following table lists all diagnostic rules, their root causes, and repair suggestions.

Rule group	Rule name	Root cause	Repair suggestion
Dockerfile syntax detection	Invalid port definition	The port or protocol format in the `EXPOSE` instruction is incorrect.	Make sure the port range is 0–65535 and the protocol is TCP or UDP.
Dockerfile syntax detection	Copy instruction: destination not a directory	When copying multiple files, the destination path is not a directory.	Use a directory path as the destination.
Dockerfile syntax detection	The building stage does not exist	The stage name in the `COPY` instruction does not refer to a defined stage.	Use a stage name that was defined earlier in the Dockerfile.
Dockerfile syntax detection	Duplicate stage name	Two or more build stages share the same name.	Use a unique name for each stage.
Dockerfile syntax detection	Invalid first instruction	The first instruction is not `FROM` or `ARG`.	Start the Dockerfile with a `FROM` or `ARG` instruction.
Dockerfile syntax detection	Compilation error item	The Dockerfile contains precompilation errors.	Fix the syntax errors, or wait for repair suggestions from root cause analysis.
Dockerfile syntax detection	Compilation warning item	The Dockerfile has precompilation warnings.	Review the flagged instructions—they may run in unexpected ways.
Image tag detection	No base image tag specified	The `FROM` instruction does not specify a tag.	Pin a specific image tag to avoid pulling an unintended version during future builds.
Image tag detection	Base image does not exist	The base image name is incorrect or the image does not exist.	Check the image name or select a different base image.
Runtime error detection	Command execution error	A command in the Dockerfile exits with an error.	Check that the commands in your Dockerfile are correct, or wait for repair suggestions from root cause analysis.
Runtime error detection	Command does not exist	A command to be run is not present in the base image.	Make sure every command your Dockerfile runs exists in the base image.
Runtime error detection	File does not exist	A `COPY` instruction references a file or directory that does not exist.	Check that the file or directory path in the `COPY` instruction is correct.
Invalid instruction detection	Invalid command	Instructions such as `Kill` or `Shutdown` are used during the build.	Remove `Kill`, `Shutdown`, and similar instructions—they cause security and stability issues.
Invalid instruction detection	sudo command	`sudo` is used during the build.	Remove `sudo` from the build process. Using `sudo` during a build produces unpredictable behavior because privilege escalation does not work the same way inside a container build context.
Detection of errors in the uploading stage	Tag conflict	The image tag to be pushed conflicts with an existing tag in the repository.	Disable the immutable image tag feature for the repository, or avoid pushing to the same tag repeatedly.
Image size optimization	apt-get: update and install separated	`apt update` and `apt install` are in separate `RUN` instructions.	Combine `apt-get update` and `apt-get install` in a single `RUN` instruction. Docker caches each `RUN` layer independently. If `apt-get update` runs in one layer and `apt-get install` in another, a subsequent build can reuse the cached `apt-get update` layer while fetching packages—resulting in stale package versions and a larger image.
Image size optimization	apt-get: missing --no-install-recommends	`apt-get install` does not include the `--no-install-recommends` flag.	Add `--no-install-recommends` to `apt-get install` to skip optional recommended packages and keep the image smaller.
Image size optimization	Package cache not cleared	The package manager cache is not removed after installation.	Clear the cache in the same `RUN` instruction that installs the package: use `apt-get clean` on Ubuntu, `apk add --no-cache` or `rm -rf /var/cache/apk/*` on Alpine, and `yum clean` on CentOS. Clearing in the same instruction ensures the cache is not committed to an image layer.
Image size optimization	Multi-stage build not used	Compilation happens in the final image stage.	Move compilation into a separate build stage and copy only the build output into the business image. This keeps compiler toolchains and intermediate artifacts out of the production image.
Image size optimization	Compressed packages not removed	Archives downloaded during the build are not deleted.	Combine the download, extract, and delete steps in a single `RUN` instruction so that the archive is not committed to an image layer.
Build instruction optimization	Relative WORKDIR path	`WORKDIR` uses a relative path.	Use an absolute path for `WORKDIR`. A relative path is resolved against the current working directory of the base image, which can change between base image versions and cause unexpected build failures.
Build instruction optimization	Root user during build	The build switches to the root user.	Remove instructions that switch to root. Running as root during a build can introduce security risks at container runtime.
Build instruction optimization	cd used instead of WORKDIR	`cd` is used to change directories during the build.	Replace `cd` with the `WORKDIR` instruction. Directory changes made with `cd` in a `RUN` step do not persist to the next step or to the container at runtime—only `WORKDIR` changes the working directory across layers.
Build instruction optimization	Multiple CMD or ENTRYPOINT instructions	More than one `CMD` or `ENTRYPOINT` instruction appears in the Dockerfile.	Only the last `CMD` or `ENTRYPOINT` instruction takes effect. Remove all but the intended final instruction.