Skip to main content

Troubleshooting Deployment and Image Errors

When you deploy tasks in flyte-sdk, failures can occur during the registration phase or later when the container runtime attempts to execute the code. These errors are represented by specific exception classes that help identify whether the issue is a configuration mistake, a build failure, or a runtime environment problem.

General Deployment Failures​

The DeploymentError is raised when the SDK fails to register a task with the Flyte backend or when local preconditions for deployment are not met.

Missing Version with No Copy Style​

If you attempt to deploy with copy_style="none", you must provide an explicit version. The flyte-sdk raises a DeploymentError immediately if this is missing.

import flyte
from flyte import Environment

env = Environment(name="prod")

# This will raise flyte.errors.DeploymentError: 
# "Version must be set when copy_style is none"
flyte.deploy(env, copy_style="none")

Task Registration Failures​

During the apply phase of deployment, the flyte-sdk wraps any underlying exceptions (such as gRPC communication errors) in a DeploymentError to provide context about which task and image failed.

# Example of the error message structure generated in _deploy.py:
# "Failed to deploy task {task.name} file {task.source_file} with image {image_uri}, Error: {e!s}"

Image Build Failures​

When using the remote image builder, ImageBuildError indicates that the process of creating your container image failed before deployment could complete.

Remote Builder Unavailable​

If the remote image builder is not enabled for your project or the system task is unreachable, the SDK raises an ImageBuildError.

# Raised in _internal/imagebuild/remote_builder.py
# "remote image builder is not enabled. Please contact Union support to enable it."

Build Execution Failure​

If the build starts but fails to complete (e.g., due to a broken pip install or invalid Dockerfile commands), the error message includes a direct link to the build logs.

# Example error from _internal/imagebuild/remote_builder.py:
# "❌ Build failed in 0:02:15 at https://flyte.example.com/console/projects/system/domains/production/executions/..."

Troubleshooting Step: Always click the URL provided in the ImageBuildError message to inspect the detailed logs from the build environment.

Container Runtime Errors​

Several errors are client-side representations of failures reported by the Flyte backend during task execution. These are converted from server-side error codes in _internal/runtime/convert.py.

Image Pull and Naming Errors​

If the backend cannot retrieve the image you specified, it returns specific codes that the SDK maps to these exceptions:

  • InvalidImageNameError: The image URI provided is syntactically incorrect or formatted in a way the container registry cannot parse.
  • ImagePullBackOffError: The image exists but cannot be pulled, often due to authentication failures (missing secrets) or the image not being found in the registry.

Primary Container Not Found​

The PrimaryContainerNotFoundError is raised when the Flyte backend attempts to execute a task but cannot find the main container defined in the pod specification. This usually indicates a mismatch between the task definition and the execution environment's expectations.

Troubleshooting Runtime Errors​

Because these errors originate on the server, debugging requires checking the Flyte console or Kubernetes logs:

  1. Verify the image string in your Task or Environment definition.
  2. Ensure the container registry credentials (image pull secrets) are correctly configured in the target namespace.
  3. Check the "User Logs" and "System Logs" in the Flyte console for the specific execution.