Troubleshoot builds#

When cs inspect, cs build --dry-run, cs build, or the GitHub Action fails, start with the local preflight:

cs inspect
cs build --dry-run

The GitHub Action runs the same dry run before it writes artifacts.

Project root not found#

Error:

could not find project root containing conda.toml, pixi.toml, or supported pyproject.toml

Fix:

  • run cs from the project directory, or

  • pass --root PATH, or

  • set the GitHub Action root input.

For pyproject.toml, add a nonempty [tool.conda.workspace] or [tool.pixi.workspace] table. [tool.conda-ship] alone is build policy and does not define the source workspace. See Configuration reference.

Lockfile not found#

Error:

lockfile not found at conda.lock

Fix the lockfile with the tool that owns the manifest:

conda workspace lock

or:

pixi lock

Commit the lockfile before using the GitHub Action.

Source environment missing#

Error:

source environment is required

Fix:

[tool.conda-ship]
source-environment = "ship"

conda-ship does not fall back to a default environment because that can accidentally ship development or test dependencies.

Runtime version is missing#

Error:

runtime version is required

Fix:

[tool.conda-ship]
runtime-version = "1.0.0"

For Python projects with static metadata, conda-ship can use [project].version from the selected pyproject.toml. For projects with dynamic = ["version"], the Python conda ship adapter can resolve PEP 517 project metadata:

[tool.conda-ship]
runtime-version = { from = "project-metadata" }

When using the standalone cs binary directly, pass --runtime-version with a concrete value instead.

Source environment not in the lockfile#

Error:

source environment "ship" not found

Fix:

  • add the environment to conda.toml, pixi.toml, or pyproject.toml

  • refresh the matching lockfile

  • rerun cs inspect

Runtime template not found#

Error:

runtime template not found

Packaged builds look for cs-template next to cs. Source checkouts do not compile a template implicitly.

Fix by either:

  • installing conda-ship from a package that includes cs-template

  • setting CONDA_SHIP_TEMPLATE

  • passing --template PATH

Cross-builds require an explicit template for the requested target.

Build missing SHA256 data#

Error:

cannot ship packages without SHA256 hashes

All layouts need SHA256 package hashes so package archives can be verified. Refresh the source lockfile with a tool/version that records SHA256 metadata for the selected packages.

Invalid runtime, delegate, target, or install method#

Identifier-like values must start with an ASCII letter or digit and may contain only ASCII letters, digits, dots, dashes, and underscores.

Examples:

demo
demo-runtime
x86_64-unknown-linux-gnu
homebrew

Avoid path-like values such as demo/runtime or shell-like values with spaces.

Runtime refuses an existing prefix#

Error:

refusing to use unmanaged install path

The runtime found an existing conda prefix without its ownership metadata. Use CONDA_SHIP_PREFIX to choose another path, such as CONDA_SHIP_PREFIX=/tmp/demo demo info, or remove the old prefix yourself if you know it is safe. Runtime-specific _PREFIX variables also work for names other than conda.

Generated runtimes refuse unmanaged prefixes to avoid deleting or mutating conda installations they did not create.