Build issues

Java build fails — missing build dependency

During a Java build, Flow downloads the dependencies declared in your settings.xml file. Flow provides the Alibaba Cloud Maven public repository as the download source. If your project relies on non-standard dependency files that you created yourself, the Flow build fails with an error similar to the following:

[ERROR] Failed to execute goal on project xxx: Could not resolve dependencies for project com.xxx:xxx:jar:1.0-SNAPSHOT: Could not find artifact com.xxx:xxx:jar:1.0 in mirror (https://maven.aliyun.com/nexus/content/groups/public)

To let Flow download the dependencies your build needs, configure it in one of the following three ways.

Java build is slow — no valid cache directory set

When a Flow pipeline runs, each job creates a new build environment that is destroyed after the build finishes. To avoid downloading build dependencies repeatedly during pipeline runs and to improve overall build efficiency, Flow provides a custom cache feature. You can define a cache directory that suits your scenario so that the cache is shared across multiple pipeline runs.

If you do not set the correct cache directory, every Java build downloads all of your project's build dependencies, even when the dependency files have not changed. The typical symptoms are as follows:

• The build still takes a long time even after multiple runs.

• The build still downloads a large number of build dependencies even after multiple runs.

  [INFO] Downloading from mirror: https://maven.aliyun.com/nexus/content/groups/public/org/apache/...
  [INFO] Downloaded from mirror: https://maven.aliyun.com/nexus/content/groups/public/org/apache/...
  ...(large number of dependencies downloaded repeatedly)

Your scenario matches one of the following:

• You do not use an organization-level custom settings.xml (in the code repository root directory or the organization custom Maven configuration).

• You use an organization-level custom settings.xml (in the code repository root directory or the organization custom Maven configuration), but the settings.xml does not contain the custom cache directory node <localRepository></localRepository>.

In the pipeline editor, go to Variables and Cache and add the Maven cache directory /root/.m2.

Speed-up effect

A pipeline with a cache directory downloads the dependencies you need only on the first build. Subsequent builds load the dependencies directly from the cache.

The more dependency files a project has, the more noticeable the cache speed-up.

Java build is slow — cache files deleted

When a Flow pipeline runs, each job creates a new build environment that is destroyed after the build finishes. To avoid downloading build dependencies repeatedly during pipeline runs and to improve overall build efficiency, Flow provides a custom cache feature. You can define your own cache directory so that the cache is shared across multiple pipeline runs.

If you use rm -rf in your build command to delete some cache files, dependencies are downloaded again on every build, which slows the build down.

If you are concerned that the pipeline will not pull snapshot packages in time after they are updated, change your build command as follows:

mvn -B clean package -Dmaven.test.skip=true -Dautoconfig.skip -U

Adding -U to the build command does the following:

• For release versions, if the package already exists in the cache, it is not downloaded again.

• For snapshot versions, a refresh is forced regardless of whether the package exists in the cache. A refresh does not mean the JAR is downloaded again: only a few small files are downloaded to check whether the local and remote repository versions match, and the JAR is downloaded only if needed.

Java build is slow — custom Maven configuration

When you use an organization-level custom settings.xml (in the code repository root directory or the organization custom Maven configuration) and define a cache directory in <localRepository></localRepository> within the settings.xml: if you do not add this directory to the Flow pipeline cache directory, every Java build downloads all of your project's build dependencies, even when your dependency files have not changed.

You can use either of the following solutions:

• Remove the <localRepository></localRepository> node from your organization-level custom settings.xml (in the code repository root directory or the organization custom Maven configuration) to use the default cache directory, and make sure you add the Maven cache directory /root/.m2 in the pipeline editor under Variables and Cache.

  Important

  Make sure the cache directory is correct and the toggle is turned on.

• In your organization-level custom settings.xml (in the code repository root directory or the organization custom Maven configuration), add the directory in the <localRepository></localRepository> node to the cache directory in the pipeline editor under Variables and Cache. Note: make sure the cache directory is correct and the toggle is turned on.

Java build error: Could not resolve dependencies for project com.xxx

Symptom:A missing dependency causes the build to fail with an error similar to the following.

[ERROR] Failed to execute goal on project xxx: Could not resolve dependencies for project com.xxx:xxx:jar:1.0-SNAPSHOT:
Could not find artifact com.xxx:xxx:jar:1.0 in Chinese_repo (https://xxx.com/repository/xxx/)
[ERROR] Build FAILURE

Solution: Check the following items in settings.xml:

• Make sure a repository entry exists for the repository that hosts the missing dependency.

• Confirm that the dependency exists in the target repository.

• Check whether activeProfiles in settings.xml has the target repository enabled.

• Check whether the <snapshots> or <releases> element for the target repository in settings.xml or pom.xml is set to false. If so, set it to true.

You can also refer to Maven dependency settings to check whether the settings.xml used by the pipeline build is as expected.

Java build is slow — downloading overseas dependencies

When you run a Java build with Yunxiao Flow, Flow supports three ways to provide the settings.xml for the Maven configuration:

• The settings.xml file in the root directory of the code repository.

• The settings.xml file uploaded under Flow Organization Settings > Maven Settings.

• The Yunxiao default Maven configuration settings.xml file.

With the third method, the Yunxiao default Maven configuration automatically connects to the Alibaba Cloud organization private repository and the Alibaba Cloud public proxy repository.

If you use one of the first two methods with an organization custom settings file (in the code repository root directory or the organization custom Maven configuration) and the settings.xml does not configure a China-based proxy repository, all of your public build dependencies are downloaded from the overseas Maven Central repository, which slows the build down. The typical symptoms are as follows:

[INFO] Downloading from central: https://repo1.maven.org/maven2/org/apache/...
[INFO] Downloading from central: https://repo1.maven.org/maven2/com/google/...
...(downloaded from the overseas Maven Central repository, slow)
[INFO] BUILD SUCCESS

Acceleration solution

Optimize your organization settings.xml file (in the code repository root directory or the organization custom Maven configuration) by adding the Alibaba Cloud public proxy repository, as follows:

<mirrors>
 <mirror>    
  <id>mirror</id>    
  <mirrorOf>central,jcenter</mirrorOf>
  <name>aliyunmaven</name>
  <url>https://maven.aliyun.com/nexus/content/groups/public</url>
 </mirror>
</mirrors>

Speed-up effect

Downloading public dependencies from the Alibaba Cloud public proxy repository is faster and more stable.

[INFO] Downloading from mirror: https://maven.aliyun.com/nexus/content/groups/public/org/apache/...
[INFO] Downloaded from mirror: https://maven.aliyun.com/nexus/content/groups/public/...
...(downloaded from the Alibaba Cloud proxy repository, faster and more stable)
[INFO] BUILD SUCCESS
[INFO] Total time: 3.968 s

Java build fails: latest dependency package not pulled

Symptom:The build fails because the latest dependency package is not pulled.

Solution:

• If the latest dependency package uses a new version number, check whether the version number is updated accordingly in the pom file.

• If the latest dependency package keeps the old version number (an existing package was overwritten with the same version), use the following solution.

  • If the dependency package is a snapshot version, use the -U parameter to force a refresh. See the following example build command:

    mvn -B clean package -Dmaven.test.skip=true -Dautoconfig.skip -U

  • If the dependency package is a release version, the cause may be that the old release package is already cached by Flow. Because the version has not changed, the latest package is not downloaded again during the build. Refer to Cache settings to clear the cache and try again.

Java build download of JAR packages hangs

The log shows that a JAR download stops before completing. This happens because the JAR download failed. First check whether the Maven source is a China-based mirror. We recommend using the Alibaba Cloud Maven mirror repository to accelerate dependency downloads.

Java build stuck in the queue

When a pipeline stage shows "Queued, please wait", it is usually because the pipeline's users commit code frequently, or code-commit tasks from multiple users pile up, so that many triggered runs have not finished and the queue backs up. As a result, the latest run stays queued. We recommend that you manually stop the current or historical runs to clear the queue.

Maven dependency download error: the uploaded package is faulty or cannot be found

This is usually caused by a second-party library dependency. Troubleshoot in this order: first confirm the private repository address used to download the dependency (the default settings.xml file is located at ~/.m2/settings.xml ), then log on to the repository to check whether the dependency exists.

If the dependency exists and you use the private repository provided by Yunxiao (repo.rdc.aliyun.com), you can contact Yunxiao support for help.

Log shows: pom.xml file does not exist

Check whether the code was cloned successfully. If it was, make sure that a pom.xml file exists in the root directory of the code repository.

How to obtain Java build artifacts during an image build

In a Flow pipeline, the workspaces of different jobs are isolated from each other. To place the Java build step and the image build step in the same job, choose one of the following tasks.

In the process configuration, select the Image Build category and choose the Java Image Build task, which completes both the Java build and the Docker image build in the same job.

Gradle build error ./gradlew: No such file or directory

Symptom:The build fails with ./gradlew: No such file or directory, as shown below.

$ ./gradlew build
/bin/bash: ./gradlew: No such file or directory

Solution:Flow does not provide a built-in Gradle. We recommend using Gradle Wrapper. Check whether a gradlew file exists in your code directory. If not, upload the gradlew file and try again.

Gradle build error ./gradlew: Permission denied

Symptom:The build fails with ./gradlew：Permission denied, as shown below.

$ ./gradlew Build
/bin/bash: ./gradlew: Permission denied
$ ls -al
-rw-r--r-- 1 root root  gradlew

Solution:This error occurs because gradlew does not have execute permission. Add chmod +x gradlew to the build command to grant gradlew execute permission, and then try again.

Gradle build is slow or fails with a timeout

Symptom:The Gradle build is slow, or the dependency download fails with a timeout.

Solution:

• Check whether Gradle Wrapper has cross-border network issues. If so, refer to Build environment to change the download source.

• Check the build log for cross-border dependency downloads. If any exist, edit the build.gradle file to point the dependency repositories to a China-based proxy, as shown below.

buildscript {
    repositories {
        maven {
            url 'http://maven.aliyun.com/nexus/content/groups/public/'
        }
        maven {
            url 'http://maven.aliyun.com/nexus/content/repositories/jcenter'
        }
    }
}

allprojects {
    repositories {
        maven {
            url 'http://maven.aliyun.com/nexus/content/groups/public/'
        }
        maven {
            url 'http://maven.aliyun.com/nexus/content/repositories/jcenter'
        }
    }
}

nohup: failed to run command 'java': No such file or directory

If you encounter the nohup: failed to run command 'java': No such file or directory error during a pipeline build or in a remote execution environment, it is usually caused by one of the following, each with its own solution:

• Java path issue

  A non-interactive shell (such as Jenkins) may not load user environment variables (such as PATH or JAVA_HOME). Specify the absolute path to Java explicitly in the script (for example /usr/bin/java), or run source /etc/profile to load environment variables before running the command.

• Service process management

  By default, the pipeline terminates spawned processes after the build finishes. Set BUILD_ID=dontKillMe in the script and redirect the output (for example > nohup.out 2>&1) to prevent the process from being terminated.

• Permission issue

  Make sure the Java executable (such as /usr/bin/java) and the JAR file have execute permission. You can fix this with chmod +x.

The solution is as follows:

#!/bin/bash
# Load environment variables and set BUILD_ID
source /etc/profile
BUILD_ID=dontKillMe
# Start the JAR with an absolute path and redirect output
nohup /usr/bin/java -jar your_app.jar > nohup.out 2>&1 &

If the problem persists, check whether Java is installed and whether the environment variable configuration takes effect globally, or try declaring the JAVA_HOME path directly in the script.

Which JDK versions does the JavaBuild step of a Yunxiao pipeline support?

Symptom:The pipeline Java build needs a higher JDK version such as JDK 21 or JDK 25, which the default environment does not support.

Solution:

The default build environment of the Yunxiao Maven task supports up to JDK 17. To use a higher version (such as JDK 21 or JDK 25), choose one of the following options:

• Option 1: Use a custom Docker image (Specify container environment): Build an image that contains the target JDK version, push it to ACR or another image repository, and in the pipeline job configuration select Specify container environment and enter the image address.

• Option 2: Use Specify container environment on a public cluster or VPC-hosted cluster, or a private build cluster (Default VM environment): In the pipeline job configuration, select Specify container environment (for public clusters and VPC-hosted clusters) and enter the address of an image that contains the target JDK version; or select Default VM environment (for private build clusters), where the build runs directly on the host. Make sure the target JDK version is preinstalled on the host.

What is the difference between the clean install and clean deploy commands? Is purge-local-repository needed?

• mvn clean install: After compiling and packaging, installs the build artifact into the local Maven repository (~/.m2), and does not upload it to a remote private server.

• mvn clean deploy: After compiling and packaging, publishes the artifact to the settings.xml-configured remote artifact repository, for scenarios where you need to share packages to a team private server.

• dependency:purge-local-repository: Clears the local cache and forces dependencies to be downloaded again. It is an optional command that you use only when you encounter dependency conflicts or local cache pollution.

What if a new pipeline cannot pull Maven dependencies from an old artifact repository?

Troubleshoot as follows:

1. Check whether the settings.xml in the pipeline build settings includes the address and credential configuration of the target artifact repository.

2. Edit the pipeline, clear the build cache, and run it again.

3. Confirm that the dependency coordinates (groupId/artifactId/version) exist in the artifact repository and that the version matches.

If the problem persists, verify that the repository address in the settings.xml configuration matches the actual address of the artifact repository.

PHP build error: requested PHP extension xxx is missing from your system

Symptom:composer install fails because of a missing dependency.

Solution:Install the required dependency with the apt-get install xxx or yum install xxx command.

PHP build: Composer version does not meet requirements

Symptom:A Composer version issue causes the PHP build to fail.

Solution:The default Yunxiao PHP environment provides Composer 1.8.6. Use the following command to upgrade Composer to 2.1.5.

wget https://rdc-public-software.oss-cn-hangzhou.aliyuncs.com/composer/2.1.5/composer.phar -O /usr/local/bin/composer

Go build error: not found: xxx, cannot access the repository

Symptom:The Go build reports not found xxx and cannot access the repository.

go: xxx@v1.0.0: invalid version: git ls-remote -q origin in /root/go/pkg/mod/cache/vcs/xxx:
exit status 128:
  Fatal: could not read Username for 'https://xxx.com': terminal prompts disabled

Solution:During a Go build, if you need to download dependencies from a private registry, configure the required credentials in the environment. Refer to Set dependency download credentials to configure them.

Go build error — dependency download times out: Get "https://proxy.golang.org/...": dial tcp: i/o timeout

Symptom: Pulling dependencies times out with an error such as Get "https://proxy.golang.org/xxxxxx": dial tcp xxxxx: i/o timeout. This is because the GOPROXY environment variable is set to https://proxy.golang.org,direct. https://proxy.golang.org is the official Google Go proxy and is unreachable or slow from within China. You can verify the current value by running go env.

Solution: Configure a China-based proxy:

go env -w GOPROXY=https://mirrors.aliyun.com/goproxy/,direct

Go build is slow because it downloads overseas dependencies

Symptom:Downloading build dependencies directly from overseas repositories such as GitHub slows the build down.

Solution:We recommend adding the following command to set a China-based proxy.

export GOPROXY=https://goproxy.cn

Go build error: no rule to make target build

Symptom:Running a Go build with make build reports no rule to make target build.

Solution:

1. Running make build requires a makefile in the code repository. Check whether this file exists in your code.

2. Change the command in the pipeline to a build command that works locally.

Go build error when pulling dependencies: could not read Username for 'https://xxxxxxxx': terminal prompts disabled

Solution:

• Check whether the import path of the dependency is correct.

• Check whether the repository is a private repository. If it is, configure the access credentials by referring to How to use Go dependency management.

Go build error: invalid version: unknown revision v1.0.3

Symptom: The build fails when pulling a Go dependency with xxxxxx@v1.0.3: invalid version: unknown revision v1.0.3.

Solution: Check whether the corresponding release tag (for example v1.0.3) exists in the code repository that provides this dependency.

Go build error — HTTPS clone: account or password is incorrect

Symptom: Pulling a Go dependency over HTTPS fails because the git clone credentials are incorrect.

Solution: Check whether the username and password used by git clone are correct. When both .netrc and .gitconfig are present, .gitconfig takes precedence.

Go build error: go.mod has malformed module path

Symptom: Pulling a module fails with an error indicating a malformed module path.

Solution: The version declaration in the module being pulled (the module field in its go.mod) is inconsistent with the module path in your project's go.mod. Make sure the git address of the repository matches the module path.

Golang build download of dependencies hangs

The log shows that dependency downloading stops before completing, which may be because an overseas Go mirror is used. Alibaba Cloud provides an official Go Module proxy repository service that avoids slow or failed module fetches and speeds up the build.

Go mirror access error: unrecognized import path

This is usually caused by unstable access to an overseas Go mirror. We recommend switching to the Go mirror provided by Alibaba Cloud: https://developer.aliyun.com/mirror.

What if the Go version preinstalled in a Yunxiao pipeline is not supported (for example, error toolchain not available)?

Symptom:The project needs a higher Go version such as Go 1.26, and the build reports toolchain not available. The preinstalled Go version currently supports up to 1.25.

Solution:

• Option 1: Use a custom Docker image: In the pipeline job configuration, select Specify container environment and enter an official image that contains the target version (such as golang:1.25) or the address of a custom image.

• Option 2: Use a private build cluster: Deploy the target Go version in your own build environment, connect it to the Yunxiao pipeline, and run the build in your own environment.

The build log shows a cache hit, but the build is still slow. Why?

A cache hit only means that historical cache files are restored; it does not mean that all dependencies are ready. For example, in a Go project the go mod download step still needs to download dependencies over the network, which can take a long time on a poor network.

Recommendations:

• Check the dependency downloads in the build log to confirm whether any cross-border downloads occur.

• Try switching to a build cluster with a better network (such as the Hong Kong cluster) to improve speed.

• Configure a China-based Go proxy to accelerate dependency downloads:export GOPROXY=https://goproxy.cn

Node.js project build fails with the Install Nodejs ... failed error

Symptom:Installing Node.js fails while building a Node.js project. The specific error is as follows:

Install Nodejs ... failed
legacy-peer-deps=true Failed

Solution:First check whether a .nvmrc file exists in the project root directory. If it does, delete the file and run the build again. Also make sure the deployment script uses the correct paths and that all dependencies are configured correctly.

Node.js build error JavaScript heap out of memory / exit code 134

Symptom:The build runs out of memory and reports JavaScript heap out of memory, or the process exits with exit code 134.

Solution:

• Adjust the Node.js memory parameter: Add the environment variable NODE_OPTIONS=--max_old_space_size=4096 (or a larger value) before the npm command. For example:

  NODE_OPTIONS=--max_old_space_size=4096 npm run build

• Adjust the build machine specification: In the pipeline editor, go to Advanced Settings and select a build machine specification with more cores (such as XLARGE_8C16G) to get more memory and compute resources.

• Optimize the build logic: If the largest specification still fails, scan or process large folders in batches to reduce the peak memory of a single build.

Node.js build error ERR_UNKNOWN_BUILTIN_MODULE: No such built-in module: node:sqlite

Symptom:The build reports ERR_UNKNOWN_BUILTIN_MODULE: No such built-in module: node:sqlite. The cause is an incompatible Node.js version that lacks the required built-in module (node:sqlite is available only in Node.js 22.5.0 and later).

Solution:Upgrade Node.js to version 22 or later and try again. If the problem persists, enable Debug mode to log on to the build machine for debugging (turn off Debug promptly when you finish to avoid ongoing charges).

Node.js custom step error TypeError: (0, j.tracingChannel) is not a function

Symptom:The custom step reports TypeError: (0, j.tracingChannel) is not a function. The cause is an incompatible Node.js version.

Solution:In the custom step configuration, add the environment variable FLOW_RUNNER_NODE_VERSION=20 to run the build task with Node.js 20.

How to use the Bun runtime in a Yunxiao pipeline

Symptom:The Yunxiao build environment does not preinstall Bun, so running the bun command reports bun: command not found.

Solution:Run the following command before the build command to install Bun globally:

npm install -g bun

We also recommend configuring a China-based mirror to avoid network timeouts:

npm config set registry https://registry.npmmirror.com
npm install -g bun

pnpm build fails or version is incompatible

Symptom:Newer versions such as pnpm@11 may require a higher Node.js version, which causes the build to fail or behave unexpectedly.

Solution:

1. Upgrade Node.js to version 22 or later.

2. Check for and remove the Node version specified in project configuration files (such as .nvmrc) to avoid overriding the pipeline configuration.

3. Make sure the Node.js and pnpm versions are compatible between your local environment and the Yunxiao environment.

Front-end build fails to start with npm ERR / exit code 146

Symptom:The front-end build fails to start and shows npm ERR, or the process exits with exit code 146. The cause may be a dependency fetch timeout or an abnormal connection to the target server.

Solution:

1. Switch the npm install source to a China-based mirror:

   npm install --registry=https://registry.npmmirror.com

2. Check the host group selected in the pipeline deployment step and the connection status of the machines, and confirm that the target server is running and reachable.

Python build: mirror site dependency download is slow

Symptom: Public bandwidth on the PyPI mirror site is saturated, causing dependency downloads to slow down significantly.

Solution:

• Option 1: Switch to the internal network mirror

  Write the following configuration to ~/.pip/pip.conf:

  mkdir -p ~/.pip
  cat > ~/.pip/pip.conf << EOF
  [global]
  index-url=http://mirrors.cloud.aliyuncs.com/pypi/simple/
  [install]
  trusted-host=mirrors.cloud.aliyuncs.com
  EOF

• Option 2: Enable pipeline caching

  After enabling pipeline caching, the system uploads and caches the dependency files produced during the current run. On the next pipeline execution, cached dependencies are used first to avoid repeated downloads, which significantly speeds up dependency installation. The drawback is that the cache is difficult to reuse across multiple pipelines.

• Option 3: Pull dependencies through the Packages artifact repository

  When the artifact repository is used for caching, the first time a dependency package is installed, the system checks whether it already exists in the artifact repository. If not, the artifact repository automatically pulls it from the mirror site and caches it. Subsequent pipeline runs that request the same dependency can download it directly from the artifact repository at high speed. Unlike the local cache of a single pipeline, the artifact repository supports cache sharing across multiple pipelines, enabling efficient reuse and centralized management of dependencies.

  Procedure:

  1. Create a PyPI artifact repository and configure its public network address.

  2. In the pipeline, write the artifact repository pull configuration to ~/.pip/pip.conf:

     mkdir -p ~/.pip
     cat > ~/.pip/pip.conf << EOF
     [global]
     index-url = https://XXXXXX:XXXXX@packages.aliyun.com/xxxx/pypi/repo-nxjvi
     trusted-host = packages.aliyun.com
     EOF

  The first time dependencies are pulled from the artifact repository, the download is slow. On subsequent pulls, the download speed increases significantly.

Artifact upload fails with error: the specified file or folder cannot be found

Symptom:After Flow builds the code and produces a build artifact (such as a JAR package), you must upload the artifact first so that downstream deployment tasks (such as host deployment) can obtain the download address and perform the deployment. In the upload step, you can choose a name for the artifact, which is referenced in later stages. You can specify a package path, which can be a file or a folder; the system packages it into an archive. To package multiple files or folders, click the "+" button to add more paths.

If the package path is incorrect, the artifact upload fails. A typical error is as follows:

$ ls
app-configs  Dockerfile  pom.xml  src  target
$ ls target/
classes  generated-sources  maven-archiver  maven-status  spring-boot-mp-demo.jar  spring-boot-mp-demo.jar.original

Typical error scenario: A Java project contains multiple microservices, so the Flow artifact upload step must specify the artifact subdirectory. For example, the artifact subdirectory of the spring-boot-mp-demo microservice is spring-boot-mp-demo/target/, so change the package path to spring-boot-mp-demo/target/.

Solution:Use the log of the Java build step to confirm the exact path to upload, and change the upload path accordingly.

The following default package paths for different project types are provided for reference:

• For a Maven project, this is usually target/

• For a Gradle project, this is usually build/libs/

If the log does not show a successful build, enable Debug mode to log on to the build machine, run the build command manually, and confirm the artifact file type and its directory.

[INFO] --- maven-compiler-plugin:3.8.1:compile (default-compile) @ spring-boot-mp-demo ---
[INFO] --- maven-surefire-plugin:2.22.2:test (default-test) @ spring-boot-mp-demo ---
[INFO] --- spring-boot-maven-plugin:2.3.4.RELEASE:repackage (repackage) @ spring-boot-mp-demo ---
[INFO] Replacing main artifact with repackaged archive
[INFO] BUILD SUCCESS

Step 1: Copy the debugging command and, in the local environment, run it

If a pipeline job fails, you can inspect it with the local debugging tool. In the Local Debugging Tool dialog box that opens, click Copy to get the debugging command and run it in your local terminal. Because the environment is simulated for the first time, pulling the build environment image may take a while.

xxx: Pull complete
xxx: Pull complete
...
Digest: sha256:xxx
Status: Downloaded newer image for xxx
[INFO] Start cleaning the workspace
[SUCCESS] Command executed successfully

Step 2: Debug locally

You can inspect the current environment in the failed pipeline step and reproduce the issue locally to resolve it. In the following example, the pipeline job fails at the "Java build" step, so you use the local debugging tool to enter the build environment directory and debug there.

[SUCCESS] Credential obtained successfully
work path: /root/workspace/xxx
USER_KEY=0.0.1
PIPELINE_ID=1857950
PIPELINE_NAME=local-debug
BUILD_NUMBER=3
CI_RUNTIME_VERSION=jdk1.8
$ ls
app-configs  Dockerfile  pom.xml  src  target

Node.js build download of npm packages hangs

The log stops after npm install, which may be because an overseas npm mirror is used. Replacing npm with cnpm switches to the Taobao npm mirror.

If the error persists after switching to cnpm, try switching the npm install source to a China-based mirror:

npm install --registry=https://registry.npmmirror.com

Other dependencies — for example, when you cannot download tar packages

You can upload the dependency to Get started with OSS, and then generate an external download link to download it.

Other issues

Check whether the script runs an operation that takes more than one hour. We recommend keeping each step as simple as possible. If a long-running step causes the job to time out, split it into multiple steps and run them in separate jobs.

Application deployment fails or component times out

Symptom:The application deployment step fails, or a component times out while waiting. The cause may be an unreasonable probe configuration or insufficient resources.

Troubleshooting steps:

1. Check the component YAML configuration, especially the liveness and readiness probe parameters, and confirm that the timeout is set reasonably.

2. Confirm that the image address is correct and can be pulled normally.

3. Check the resource usage (CPU/memory) of the ACK cluster to make sure resources are sufficient.

4. If you use a custom deployment script, make sure it ends with exit 0 to exit explicitly.

Code download error: Clone Failed

This usually happens because the user who triggered the pipeline does not have access to the code, or the branch configured in the input source does not exist. Check the related configuration.

npm build error: module not found

This usually happens because cnpm install was not run. Check whether the command of the relevant task includes cnpm install, and add it if it is missing.

When deploying to a private npm repository, yarn install reports 401 Unauthorized and the log shows that the token cannot be found

This is usually caused by an incorrect authToken parameter, or an incorrect account and password, in the npmrc configuration of the npm artifact repository. To learn how to obtain these values, see npm artifact management and configure them according to the repository instructions.

Build error: the upload file path does not exist

Check whether the artifact path produced by a local build matches the artifact upload path configured in the pipeline.

Does the upload file path support regular expression matching?

Regular expression matching (such as */target/*.jar) is not supported. Use a specific path format, for example:

• target/ (directory)

• target/app.jar (specific file)

Git submodule fetch error fatal: could not read Username / authentication failed

Symptom:When a submodule uses the HTTPS protocol, credentials cannot be entered interactively and the main repository's authentication is not inherited automatically, so the fetch fails.

Solution:

• Before operating on submodules in the script, run the following command to use the built-in Yunxiao ACCESS_TOKEN for password-free authentication:

  git config --global url."https://${ACCESS_TOKEN}@codeup.aliyun.com".insteadOf "https://codeup.aliyun.com"

• Or use git remote set-url to dynamically inject the account and password into the remote URL.

• Make sure the pipeline service connection has read access to the submodule repository.

Can private Git dependencies be pulled over the SSH protocol?

The Yunxiao build machine requests a new environment each time, so the SSH key is not fixed and the SSH protocol cannot be configured reliably. We recommend migrating dependencies to an npm repository, or using the HTTPS protocol together with ACCESS_TOKEN.

Custom image error /lib64/ld-linux-x86-64.so.2 not found / failed to request runtime environment

Symptom:The Yunxiao task driver is a dynamically linked Go binary that depends on the system glibc library. If the base image of your custom image lacks this library, requesting the runtime environment fails.

Solution:Switch to a base image that contains /lib64/ld-linux-x86-64.so.2, or use a base image provided by Yunxiao:

registry.cn-beijing.aliyuncs.com/rdc-builds/base:1.0

Pipeline execution hangs and does not continue

Symptom:After the pipeline starts, it stays in the running state with no error and does not proceed to the next steps.

Common causes and solutions:

• A long-running process command was run (such as npm run dev): change the test script so that it exits normally after running (add exit 0) to prevent the process from staying resident and blocking the pipeline.

• Lock file conflict: Add a cleanup step to the build command to delete the lock files, and then try again:

  rm -rf package-lock.json pnpm-lock.yaml

• A background process did not end: Check the commands line by line to locate the one that starts a background process, then find and manually stop that process on the build machine.

Does the Yunxiao pipeline execution environment support sudo?

sudo is not supported by default. Build tasks run in a restricted container environment, and for security reasons commands cannot be run with elevated privileges.

Build error spawn git ENOENT

Symptom:The build reports spawn git ENOENT. The cause is that the git tool is not installed in the custom image.

Solution:Install git in the custom image and reload it, or switch to the Yunxiao default image.

If a pipeline push fails, can it be retried on its own?

The current retry mechanism is a full retry. Retrying only the push step, or fetching a token again on its own, is not supported. We recommend splitting the business build and the image build into separate steps to avoid timeouts.

Image build reports Couldn't find the binary git when running yarn install

Symptom:The image build reports Couldn't find the binary git when running yarn install. This is a build engine version compatibility issue.

Solution:In the pipeline editor, first change the buildkit version to 9 and save, then change it back to 11 and save, and run the pipeline again.

What if a GitHub project has a high failure rate when pulling code over HTTPS?

The error is not related to the protocol. We recommend using the Hong Kong cluster for the build to improve the success rate of pulling code from GitHub.

Can the 10 MB upload size limit for Jacoco coverage reports be changed?

No. The limit is fixed at 10 MB and cannot be raised to 30 MB or any other value, for system stability and performance.

Private build cluster saturates the VPC network and affects other services

Symptom:The build consumes a large amount of VPC network bandwidth or disk resources, which affects other services on the same machine.

Solution:Create a dedicated machine for builds. Do not share the same ECS instance with production services.

Slow pulls from public mirror sites

Symptom:Pulls from public mirror sites are slow, which may be related to limited public bandwidth.

Solution:

• Use a Yunxiao VPC cluster, bind an EIP, and increase the bandwidth.

• Connect a self-managed cluster to Yunxiao for builds to optimize pull speed using your own network environment.

Command reports that the path does not exist (variable reference issue)

Symptom:When a command references a variable or a relative path, it reports that the path does not exist because of an abnormal variable reference or path resolution.

Solution:Replace the variable with a fixed absolute path in the build environment, in the following format:

/root/workspace/__flow_work/__flow_builds/{build_id}/workspace/...

Use the full absolute path to run commands such as cp, and use ls -al to verify that the file was copied successfully.

How to upgrade or specify a global Gradle version in Yunxiao Flow

Yunxiao does not support setting a global Gradle version. The version is determined by the Gradle Wrapper (gradlew) in the code repository. To change it:

1. Run the following command locally to update the Gradle Wrapper configuration:

   ./gradlew wrapper --gradle-version <target-version>

2. Commit the gradlew file and the gradle/wrapper directory to the code repository.

3. Make sure the code root directory contains the gradlew file. If there is a permission issue, add the following to the build command:

   chmod +x gradlew

Calling the Container Registry API returns AUTHENTICATION_FAILED / USER_NOT_EXIST

Symptom:Calling the Container Registry API returns AUTHENTICATION_FAILED or USER_NOT_EXIST. The cause is a mismatch in account permissions or identity.

Solution:Confirm that you are logged on with the team RAM user that has been granted the appropriate RAM permissions, not a personal Alibaba Cloud account. Make sure you use the correct RAM user to log on and run the pipeline task.

What if an old pipeline node does not show the JDK 25 option?

An old pipeline that does not use Specify container environment cannot select JDK 25. Solution: copy the pipeline to create a new one, and when creating it, select the Specify container environment that supports JDK 25.

Does the pipeline support GraalVM / Quarkus builds?

There are currently no preset GraalVM steps or version options. Solution: add an Execute command step to the pipeline configuration and install the required GraalVM environment yourself from the command line to complete the build.