Errors#

This page lists common conda-ship errors and the usual fix.

cs prints human-readable diagnostics by default. The conda ship adapter uses an internal structured diagnostic mode so it can show the same errors through conda without depending on terminal formatting.

Project Input#

could not find project root containing conda.toml, pixi.toml, or supported pyproject.toml: Run from the project root or pass --root PATH.
could not find conda.toml, pixi.toml, or supported pyproject.toml: Add a supported manifest to the selected root.
lockfile not found: Refresh and commit the matching source lockfile with conda workspace lock or pixi lock.
source environment is required: Set [tool.conda-ship].source-environment.
source environment "NAME" not found: Add the environment to the source manifest and refresh the source lockfile.
runtime version is required: Pass --runtime-version, set [tool.conda-ship].runtime-version, define static [project].version in the selected pyproject.toml, or opt into runtime-version = { from = "project-metadata" } through the Python conda ship adapter for dynamic Python project versions.
failed to read condarc-file: Check [tool.conda-ship].condarc-file. Relative paths start from the selected manifest directory.
failed to parse condarc-file as YAML: Fix the referenced YAML file.
condarc-file must contain a YAML mapping: Use normal condarc key and value entries rather than a top-level scalar or sequence.

Package Archives#

cannot bundle packages without SHA256 hashes: Refresh the source lockfile with package hash metadata before building external or embedded layouts.
no default environment in ... runtime.lock: The derived runtime lock is malformed. Rebuild from the source lockfile.

Template Selection#

runtime template not found: Install a conda-ship package that includes cs-template, set CONDA_SHIP_TEMPLATE, or pass --template PATH.
cross-builds require --template: Pass a prebuilt runtime template for the requested target.
runtime template is already stamped: --template points at a generated runtime instead of a generic template.

Naming#

runtime name must start with an ASCII letter or digit: Use a filename-safe runtime name such as demo or demo-runtime.
delegate executable may only contain ASCII letters, digits, dots, dashes, and underscores: Use an executable name, not a path.
target triple may only contain ASCII letters, digits, dots, dashes, and underscores: Use a target triple string, not a path to a custom target file.
installer may only contain ASCII letters, digits, dots, dashes, and underscores: Use a short installer name such as homebrew, conda-package, or standalone.

Runtime Bootstrap#

runtime template, not a runnable runtime: Run a binary produced by cs build, not the generic runtime template.
runtime has no stamped lockfile: The binary is not a properly stamped runtime. Rebuild it with cs build.
offline bootstrap requires a stamped runtime lock: Offline bootstrap requires a runtime built by cs build.
runtime bundle path is not a directory: Point the runtime-specific _BUNDLE environment variable at a directory containing package archive files, not the compressed .bundle.tar.zst file itself.

Prefix Ownership#

refusing to bootstrap into existing non-empty path: Set CONDA_SHIP_PREFIX to another path or remove the existing directory yourself. Runtime-specific _PREFIX variables also work for names other than conda.
refusing to use unmanaged install path: The prefix does not contain ownership metadata for this runtime.
refusing to use install path with invalid bootstrap state: The internal installing marker is malformed or belongs to another runtime. A non-empty prefix without matching ownership state is rejected.