Build fails in the build and push step

Resolution for memory limit during build

See Build fails when the memory limit is exceeded for resolution information.

Resolution for a container registry problem during build

In this scenario, a registry secret to access your container registry does not exist or the secret is not correct.

1. Determine which secret is used. Use the ibmcloud ce build get command to display the registry secret that is used.

2. Determine whether a .dockerconfigjson key exists. Use the ibmcloud ce secret get command for the registry secret. Note that the secret data is encoded with base64 and not directly visible; however, the secret contains credentials. In the command output, check the Data section. It must contain a key that is called .dockerconfigjson. If the .dockerconfigjson key is not displayed, then this secret is not suitable to authenticate with a container registry and you need to create a correct secret and reference it in the build. For more information, see Adding access to a private container registry.

   Example output

   $ ibmcloud code-engine secret get -n <REGISTRY_SECRET>
   Getting secret <REGISTRY_SECRET>...
   OK
   
   Name:        <REGISTRY_SECRET>
   ID:          <REGISTRY_SECRET_ID>
   Project:     <PROJECT_NAME>
   Project ID:  <PROJECT_NAMESPACE>
   Age:         8s
   Created:     2021-02-12T10:26:59-06:00 
   
   Data:
   ---
   .dockerconfigjson: <BASE64_STRING>
   

3. If the .dockerconfigjson key exists, then decode the key, which is a base64 encoded string by using the following command,

   echo "<BASE64_STRING>" | base64 -d
   {"auths":{"<REGISTRY>":{"username":"<USERNAME>","password":"<PASSWORD>","auth":"<AUTH>"}}}
   

   The output of this command typically contains one <REGISTRY> key.

4. Confirm the following information about the key:

   a. Look at the <REGISTRY> value. This value must match the image of the build.

   • If the image name is on IBM Cloud Container Registry, for example us.icr.io/aNamespace/anImage, then the <REGISTRY> needs to be us.icr.io.

   • If the image name is docker.io/aNamespace/aRepository or /aNamespace/aRepository without any hostname, then the build is using Docker Hub. In this case, the <REGISTRY> must be https://index.docker.io/v1/.

   b. Look at the <USERNAME> value. If the registry is an IBM Cloud Container Registry, then an API key must be used for authentication. The <USERNAME> needs to be iamapikey and the password needs to be an API key. See Automating access to IBM Cloud Container Registry for steps to create the API key.

   c. The credentials need to be validated. IBM Cloud® Identity and Access Management (IAM) allows permissions to be assigned in a fine-grained way. For example, a service ID with access to an IBM Cloud Container Registry namespace and the permission to pull images, might not be allowed to push images. But, this permission is what is needed in this case.

5. After you determine the changes that are needed, create a container registry secret that uses corrected values. Use the ibmcloud ce secret create --format command; for example,

   ibmcloud ce secret create --format registry --name <REGISTRY_SECRET> --server <REGISTRY_SERVER> --username <USERNAME> --password <PASSWORD>
   

6. Update the build to reference the name of your registry secret.

   a. Use the ibmcloud ce build update command to update the build configuration to use the name of your registry secret; for example,

   ibmcloud ce build update --name <BUILD_NAME> --registry-secret <REGISTRY_SECRET>
   

   b. Use the ibmcloud ce buildrun submit command to submit a new build run. For the buildrun submit command, you must specify the --build option to provide the name of your build configuration. You can optionally specify the --name option to provide the name for this build run. If you specify the --name option, make sure that you use a different build run name from the failed build run, or ensure that you delete the failed build run by using the ibmcloud ce buildrun delete command. For example,

   ibmcloud ce buildrun submit --build <BUILD_NAME> --name <BUILDRUN_NAME>
   

Resolution for Dockerfile not found during build

A Docker build needs a Dockerfile that specifies how the container image is to be built. If the source repository does not contain such a file, then you need to provide this file or consider buildpacks as a build strategy. For more information, see Planning your build.

1. If the Dockerfile exists, but has a different name or is not in the root directory, then additional settings need to be specified in the build.

   • If the Dockerfile is not in the root directory of the source repository, then you must specify the --context-dir argument and provide the path to the directory that contains the Dockerfile.
   • If the Dockerfile is named something other than Dockerfile, then you must specify the --dockerfile argument and provide the name of your Dockerfile.

2. Update the build to use the --context-dir or --dockerfile options as needed.

   a. Use the ibmcloud ce build update command to update the build configuration to use the --context-dir or --dockerfile options as needed; for example,

   ibmcloud ce build update --name <BUILD_NAME> [--context-dir <CONTEXT_DIR>] [--dockerfile <DOCKERFILE_NAME>] 
   

   b. Use the ibmcloud ce buildrun submit command to submit a new build run. For the buildrun submit command, you must specify the --build option to provide the name of your build configuration. You can optionally specify the --name option to provide the name for this build run. If you specify the --name option, make sure that you use a different build run name from the failed build run, or ensure that you delete the failed build run by using the ibmcloud ce buildrun delete command. For example,

   ibmcloud ce buildrun submit --build <BUILD_NAME> --name <BUILDRUN_NAME>
   

Resolution for IBM Cloud Container Registry quota limit is reached during build

IBM Cloud Container Registry has two service plans, a free plan and a standard plan. For the free plan, IBM Cloud Container Registry applies strict limits, especially on the image size that can be stored in total (500 MB). For the standard plan, you can configure the quotas. For more information, see About IBM Cloud Container Registry.

1. Take one of the following actions:

   • Delete unused images from the IBM Cloud Container Registry namespace to increase the available space.
   • Upgrade from the free plan to the standard plan.
   • Increase the quotas of the IBM Cloud Container Registry namespace.

   The image URL is included in the error message to help you identify which IBM Cloud Container Registry namespace is affected. The namespace can be in a different IBM Cloud account than your IBM Cloud Code Engine project.

2. After you complete the corrective actions, use the ibmcloud ce buildrun submit command to submit a new build run. For the buildrun submit command, you must specify the --build option to provide the name of your build configuration. You can optionally specify the --name option to provide the name for this build run. If you specify the --name option, make sure that you use a different build run name from the failed build run, or ensure that you delete the failed build run by using the ibmcloud ce buildrun delete command. For example,

   ibmcloud ce buildrun submit --build <BUILD_NAME> --name <BUILDRUN_NAME>
   

Resolution for build source not specified correctly

The typical reason that this error occurs is that the build source is not located in the root directory of the Git repository, but in a child directory. If the build source does not reside inside the root directory, then specify the location in the build.

1. Use the ibmcloud ce build update command to update the build configuration to use the --context-dir option to specify the path to the source in the Git repository; for example,

   ibmcloud ce build update --name <BUILD_NAME> --context-dir <CONTEXT_DIR> 
   

2. Use the ibmcloud ce buildrun submit command to submit a new build run. For the buildrun submit command, you must specify the --build option to provide the name of your build configuration. You can optionally specify the --name option to provide the name for this build run. If you specify the --name option, make sure that you use a different build run name from the failed build run, or ensure that you delete the failed build run by using the ibmcloud ce buildrun delete command. For example,

   ibmcloud ce buildrun submit --build <BUILD_NAME> --name <BUILDRUN_NAME>
   

Resolution for a problem due to Docker Hub rate limits

When you pull an image from Docker Hub to use with apps or jobs in Code Engine, be aware of Docker rate limits for free plan (anonymous) users. You might experience pull limits if you receive a 429 error that indicates you reached your pull rate limit. If you receive this error, try one of the following solutions.

• Increase rate limits. You can authenticate with Docker Hub, or upgrade your account to a Docker Pro or Team subscription, if needed.

• Pull the built image from Docker Hub and publish the image in a different registry, such as IBM Cloud® Container Registry. Then, pull your image from the new location. Code Engine supports referencing a single secret. If the base image for your Dockerfile build is pulled from a different registry than where the resulting built image is published and both registries require authentication, you can use kubectl to create a Kubernetes secret of type kubernetes.io/dockerconfigjson that contains credentials to both registries. For information about working with access credentials for both registries, see Kubernetes documentation on pulling an image from a private repository.

Resolution for build source not supported by buildpacks

To check whether your build source repository is supported in Code Engine, see Choose a build strategy for supported runtimes. If your language is listed, check the linked samples and ensure that you correctly structure your sources so that buildpacks can successfully detect and build them. If you cannot find a suitable buildpack for your source or the standardized way on how buildpacks runs the build does not meet your needs, then you can specify a Dockerfile, describe the container build manually in the Dockerfile, and then switch to use the dockerfile build strategy in the build configuration.

Resolution for a problem with the Docker build

If the build and push step failure problem isn't a problem with memory, a container registry secret, or a Dockerfile, then the problem is likely with the Docker build. The problem might be an error in the Dockerfile itself, for example, a syntax error, or in the correctness of the operation that it performs. The problem can also be in your source code, which might fail to compile, for example, if Java® code is included.

If you successfully built your project locally, but the same source code does not build in Code Engine, then you might have files available locally that are not in your Git repository. For example, for Node.js projects, it is common to run the npm install command locally so that project dependencies are downloaded and placed in the node_modules directory inside the project directory. It is a good practice to include the node_modules directory in the .gitignore file to keep your Git repository small. A common mistake is to forget to also run npm install (or npm ci) in the Dockerfile. A Docker build that you run locally can access the local node_modules directory, if you copy the whole project into the container, for example, by using the COPY . /app command in the Dockerfile. But, the Code Engine build runs from a freshly checked-out Git repository and cannot access the node_modules directory. Therefore, you must run npm install (or npm ci) in the Dockerfile as part of the build.

A good practice is to include directories like node_modules also in a .dockerignore file so that the Docker build that you run locally behaves the same as the Code Engine build.

Another reason for a project to be successfully built locally but to fail as Code Engine build are security limitations. As with applications and batch jobs, Code Engine does not allow arbitrary system operations within the Code Engine cluster. Most of those system operations are not relevant for Docker builds anyway. However, Code Engine does not allow opening server sockets for privileged ports. The range is 0 to 1023. For example, if you build a web application and your build includes a test step that brings up a web application server, then you must use ports with higher numbers for this server.