Error Codes

All ANNÁVE CLI errors use the same structured format.

Error format

Plain mode (stderr)

[runtime/ERR_NOT_IMPLEMENTED] GCP cost analysis is not yet implemented — use --provider aws

JSON mode

{
  "code": "ERR_NOT_IMPLEMENTED",
  "stage": "runtime",
  "message": "GCP cost analysis is not yet implemented — use --provider aws"
}

Parse code, not message. The message wording may change between versions; the code is stable.

Summary

Error codes

ERR_NOT_IMPLEMENTED

A feature exists in the CLI but has no working adapter yet. Currently: annave cost scan --provider gcp and --provider azure.

Script handling: Exit code is 0 — printed as a notice, not an error. GCP and Azure cost providers are planned for a future release.

ERR_INVALID_INPUT

A flag value is invalid (unparseable --since date, unrecognised --format or --type value), or a required argument is missing.

Script handling: Fix the flag value. The message always includes the invalid value and the accepted alternatives.

ERR_IO_FAILURE

A file cannot be opened or read. Common causes: path does not exist, permission denied, file is a directory when a file is expected.

Script handling: Check the file path and permissions. The message includes the OS error string.

ERR_TIMEOUT

A network operation exceeded its deadline. In health checks, a per-target timeout is reported as status timeout in output and does not produce this error code — the module continues to the next target. ERR_TIMEOUT is used for module-level timeouts (e.g. the entire cleanup scan exceeds cleanup.timeout_seconds).

Script handling: Increase --timeout flag or the relevant timeout_seconds in limits.yaml.

ERR_PERMISSION

Kubernetes RBAC denied the list or get request. The kubeconfig user does not have permission to list the requested resource type in the requested namespace.

Script handling: Check RBAC for the kubeconfig user. Cleanup scan and security k8s-live audit require list and get on pods, pvcs, configmaps, namespaces, deployments, statefulsets, and services.

ERR_NOT_FOUND

A specified file, directory, or Kubernetes resource does not exist.

Script handling: Verify the path. For Kubernetes contexts, run kubectl config get-contexts to confirm the context name exists in the kubeconfig.

ERR_PARSE_FAILED

The input cannot be parsed. Common causes: malformed YAML in a Kubernetes manifest, a Terraform JSON plan that does not match the expected schema, or a log file with no lines matching any supported format.

Script handling: Verify the input file is valid for its type. For YAML, run kubectl apply --dry-run=client. For Terraform JSON, ensure the file was produced by terraform show -json plan.tfplan.

Stage values