akua pkg errors - Akua | Docs

Every akua pkg failure carries a stable error code. Agents and scripts branch on the code, never on the message.

Manifest and lockfile

Code	Meaning
`E_MANIFEST_MISSING`	The workspace has no `akua.toml`. Run the command from the Package directory, pass `--workspace`, or create one with `akua pkg init`.
`E_MANIFEST_PARSE`	`akua.toml` is not valid TOML or does not match the manifest format: an unknown or missing field, an invalid package name, or a dependency with more than one source.
`E_MANIFEST_GIT_USERINFO`	A `git` dependency URL embeds credentials (a `user:password@` part before the host). It is rejected so the secret never reaches the lockfile or git history; pass credentials with `--auth` or `--auth-file` instead.
`E_MANIFEST_HELM_MISSING_CHART`	A `repo` (HTTPS Helm repository) dependency is missing the required `chart` field.
`E_MANIFEST_HELM_MISSING_VERSION`	A `repo` dependency is missing the required `version` field. A version constraint is mandatory so renders stay reproducible.
`E_MANIFEST_HELM_USERINFO`	A `repo` dependency URL embeds credentials. It is rejected so the secret never reaches the lockfile or git history; pass credentials with `--auth` or `--auth-file` instead.
`E_MANIFEST_HELM_CHART_INVALID`	A `repo` dependency’s `chart` contains a path separator or `..`. A chart name must be a single plain name, which keeps the chart cache free of path confusion.
`E_MANIFEST_OCI_USERINFO`	An `oci` dependency URL embeds credentials (a `user:password@` part before the host). Pass credentials with `--auth`, `--auth-file` or `auth.toml` instead.
`E_LOCK_MISSING`	The workspace has no `akua.lock`. Run `akua pkg lock` to create it.
`E_LOCK_PARSE`	`akua.lock` is not valid TOML or does not match the lockfile format. Regenerate it with `akua pkg lock`.
`E_LOCK_DRIFT`	`akua lock --check` found `akua.lock` out of sync with `akua.toml`. Run `akua pkg lock` without `--check` to refresh it.
`E_DEP_KIND_MISMATCH`	`package.k` imports a dependency alias whose kind KCL cannot import, typically a Helm chart alias used as `import <alias>`. Charts are reached through `charts.<alias>`.
`E_DEP_RESOLVE`	A dependency in `akua.toml` failed to resolve: a missing path, a path outside the workspace, an OCI, Helm or git fetch failure, or a digest that disagrees with `akua.lock`.
`E_AUTH_PARSE`	An `--auth <prefix>=<user>:<password>` value or an `--auth-file` TOML payload did not parse. Distinct from `E_INVALID_FLAG` so callers can branch on credential input specifically.

Rendering

Code	Meaning
`E_PACKAGE_MISSING`	The Package file (default `./package.k`) or a directory the command needs does not exist. Pass the path explicitly or run from the Package directory.
`E_PACKAGE_PARSE`	`package.k` does not have the shape a Package needs, for example no top-level `resources` list or an `Input` schema KCL cannot load.
`E_INPUTS_MISSING`	The inputs file passed with `--inputs` does not exist or cannot be read. The message carries the operating system’s reason.
`E_INPUTS_PARSE`	The inputs file passed with `--inputs` (or found next to the Package) is not valid JSON or YAML.
`E_INVALID_FLAG`	A command-line flag or argument did not parse: an unknown flag, a missing value, or a value of the wrong shape. Distinct from `E_INPUTS_PARSE`, which is about the inputs file.
`E_RENDER_KCL`	The Package’s KCL failed: a syntax or type error, a failed `check:` block, or an engine call (Helm, Kustomize, `pkg.render`) that returned an error.
`E_PATH_ESCAPE`	A path an engine call received resolved outside the Package directory, through `..` or a symlink. The sandbox refuses it; reference files inside the Package or through a typed dependency.
`E_RENDER_CYCLE`	`pkg.render` re-entered a Package that is already being rendered: a composition cycle. It is caught before the inner Package loads.
`E_RENDER_BUDGET_DEPTH`	Nested `pkg.render` calls exceeded the render-stack depth cap. Hitting it usually means runaway composition rather than a deep but legitimate tree.
`E_RENDER_BUDGET_DEADLINE`	The render ran out of its CPU budget (the Package’s own KCL, or an engine call) before finishing. The command exits 6, the timeout exit code.
`E_RENDER_BUDGET_MEMORY`	The render’s sandbox reached its memory cap and was stopped.
`E_STRICT_UNTYPED_CHART`	`akua pkg render --strict` found an engine call given a raw chart path instead of a typed `charts.<alias>` dependency. Declare the chart in `akua.toml` and reference it through its alias.
`E_COSIGN_VERIFY`	A cosign signature failed verification, or its payload disagrees with the fetched digest. Treat it as tampering until proven otherwise.
`E_COSIGN_SIG_MISSING`	A cosign public key is configured but the registry has no `.sig` sidecar for the artifact, or it is malformed. The publisher has not signed this version.

Commands

Code	Meaning
`E_INIT_EXISTS`	`akua pkg init` would overwrite `akua.toml`, `package.k` or `inputs.example.yaml`. Pass `--force` to overwrite, or choose another directory.
`E_INIT_EMPTY_NAME`	`akua pkg init` could not derive a package name: the directory name has no usable characters. Pass a name explicitly.
`E_FMT_KCL`	`akua pkg fmt` could not parse the file it was asked to format.
`E_LINT_FAIL`	`akua pkg lint` found the Package’s KCL does not parse or imports something that does not resolve.
`E_INSPECT_FAIL`	`akua pkg inspect` could not read the Package’s input surface: the KCL does not load, a tarball has no `package.k`, or the exported schema is not an object.
`E_DIFF_NOT_DIR`	An argument to `akua pkg diff` is a file or a symlink, not a directory.
`E_ADD_DEP_EXISTS`	`akua pkg add` was given an alias `akua.toml` already declares. Remove it first or pick another alias.
`E_ADD_INVALID_DEP`	`akua pkg add` or `akua pkg update` was given a dependency that is not valid: no source, more than one source, or a field the source kind does not allow.
`E_REMOVE_NOT_FOUND`	`akua pkg remove` was given an alias `akua.toml` does not declare. Pass `--ignore-missing` to make that a no-op.
`E_VENDOR_DEP_MISSING`	`akua pkg vendor add` was given an alias `akua.toml` does not declare.
`E_VENDOR_DRIFT`	`akua pkg vendor check` found a vendored tree under `.akua/vendor/` whose contents no longer match the digest `akua.lock` pins. Re-run `akua pkg vendor add`.

Distribution

Code	Meaning
`E_PUBLISH_FAILED`	`akua pkg publish` or `akua pkg push` could not upload the artifact: the registry rejected authentication, an upload request failed, or the manifest was refused.
`E_PULL_FAILED`	`akua pkg pull` or `akua pkg inspect --oci` could not retrieve or unpack the requested artifact.

General

Code	Meaning
`E_IO`	A file or directory could not be read or written. The message carries the operating system’s reason, such as a permission denial.

akua pkg commands

Every command, the universal flags and the exit codes.

Package format

The package.k Input schema and UI annotations.