# 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. A `pyproject.toml` needs a
  nonempty `[tool.conda.workspace]` or `[tool.pixi.workspace]` table.
  `[tool.conda-ship]` alone does not define a source workspace.

`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.

`source environment "NAME" contains unsupported PyPI packages`
: Diagnostic kind: `unsupported_pypi_packages`. Use conda packages or select a
  source environment containing only conda packages, then refresh the lockfile
  with `conda workspace lock` or `pixi lock`.

`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.

`runtime template is incompatible with authenticated runtime data`
: Mach-O and PE templates must contain the exact reader ABI declaration from
  the current format implementation in its dedicated image section. Use
  `cs-template` from the same conda-ship release as the builder. conda-ship
  0.9.0 rejects native templates from 0.8.0 and earlier even when their
  executable layout could otherwise be stamped. The declaration is not proof
  of template provenance.

`universal Mach-O binaries are not supported`
: Use a thin macOS template for the selected target. The builder also rejects
  32-bit and big-endian Mach-O templates.

`Mach-O runtime template is not an executable image`
: Use a thin `MH_EXECUTE` template, not a dynamic library or another Mach-O
  file type.

`Mach-O runtime template CPU type ... with subtype ... does not match platform ...`
: Use an x86_64 template for `osx-64` and an arm64 template for `osx-arm64`.

`unsupported Mach-O load command: ...`
: Rebuild with the matching `cs-template`. conda-ship accepts the bounded set of
  modern load commands used by its runtime templates and fails closed on
  unknown commands that might reference removed signature bytes.

`Mach-O runtime template targets unsupported platform ...`
: Use a macOS template. iOS, Catalyst, simulator, and other Apple platform
  binaries are not accepted.

`Mach-O code signature overlaps referenced file data`
: Rebuild the template with a linker-generated signature after all link-edit
  tables. conda-ship will not truncate data referenced by another load command.

`Mach-O LC_MAIN entry point is outside executable file data`
: Rebuild the template as a normal modern macOS executable with one `LC_MAIN`
  entry point inside an executable segment.

`Mach-O header has no room for a code signature command`
: An unsigned custom template needs at least 16 bytes between its load-command
  table and first file-backed section so native `codesign` can add
  `LC_CODE_SIGNATURE`. Use a linker-generated signature or reserve that space.

`Mach-O code signature is not the final data in the file`
: Rebuild the custom template so its linker-generated signature is the final
  file data before conda-ship stamps it.

`Mach-O load command table is too large`
: Rebuild the custom template with a normal thin Mach-O load-command table.
  conda-ship rejects tables larger than 1 MiB before allocating memory for
  them.

`PE certificate table is not the final data in the file`
: Finalize the PE so its Security Directory certificate range ends at the
  physical end of the executable. Do not append data after Authenticode
  signing.

`signed PE runtime data has no authenticated anchor section`
: Rebuild the Windows runtime with a matching conda-ship 0.9.0 builder and
  template, then apply Authenticode signing to the new artifact. A legacy
  signed PE overlay cannot be repaired by re-signing it. A Windows runtime from
  0.8.0 or earlier also cannot consume a 0.9.0 executable update candidate, so
  an adopting installer or package manager must record external ownership
  during replacement. An installation that must remain directly managed needs
  a fresh install that does not reuse its old direct-install metadata.

`signed PE templates must be unsigned before runtime stamping`
: Remove the existing Authenticode signature or rebuild an unsigned template.
  Sign the generated runtime after conda-ship adds its `.cship` anchor.

`PE runtime template has data outside its declared sections`
: Rebuild the template without an existing overlay. conda-ship creates the
  runtime overlay itself and binds it to the signed `.cship` footer.

`PE headers have no room for a runtime anchor section`
: Rebuild the template with at least one zero-filled 40-byte section-header slot
  before the first raw section.

`PE runtime template machine ... with image kind ... does not match platform ...`
: Use a PE32 x86 template for `win-32`, a PE32+ x86_64 template for `win-64`,
  and a PE32+ ARM64 template for `win-arm64`.

## 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.