Common Errors

Common Errors#

Quick reference for frequently encountered APX errors and their solutions.

Configuration Errors#

apx.yaml not found#

Error: apx.yaml not found in current directory or parent directories

Cause: APX commands that need configuration can’t find apx.yaml.

Fix: Either:

  • Run apx init app or apx init canonical to create one

  • Use --config /path/to/apx.yaml to specify a custom location

  • Ensure you’re in the repository root directory

apx.yaml already exists#

Error: apx.yaml already exists

Cause: apx init or apx config init won’t overwrite an existing config.

Fix: Delete or rename the existing file, or edit it directly.

Configuration validation failed (exit code 6)#

Error: configuration is invalid
  - field "org": missing required field
  - field "language_targets.go.plugins": invalid type

Cause: apx.yaml has structural or value errors.

Fix: Run apx config validate to see all errors, then fix them. Run apx config migrate if the issue is a schema version mismatch.

Schema Format Detection#

could not detect schema format#

Error: could not detect schema format for path: internal/apis/

Cause: APX couldn’t find recognizable schema files (.proto, .yaml, .avsc, etc.) in the given directory.

Fix:

  • Verify the path points to a directory containing schema files

  • Use --format proto (or openapi, avro, etc.) to specify the format explicitly

  • Check that module_roots in apx.yaml points to the correct directory

Identity Errors#

invalid API ID format#

Error: invalid API ID: "payments/ledger"
  Expected format: <format>/<domain>/<name>/<line>
  Example: proto/payments/ledger/v1

Cause: The API ID is missing required components.

Fix: Include all four parts: format, domain, name, and version line.

version incompatible with API line#

Error: version v2.0.0 is incompatible with API line v1

Cause: The SemVer major version doesn’t match the declared API line.

Fix: Use a version that matches the line (e.g. v1.x.x for the v1 line), or create a new API line for breaking changes.

lifecycle-version mismatch#

Error: lifecycle "stable" requires a stable version (no prerelease), got v1.0.0-beta.1

Cause: The version’s prerelease tag doesn’t match the declared lifecycle.

Fix: See Release Guardrails for the compatibility matrix.

Tool Resolution#

failed to resolve buf#

Error: failed to resolve buf: tool not found in .apx-tools/

Cause: The Buf CLI is not cached locally.

Fix: Run apx fetch to download and cache all pinned tools.

buf: executable file not found in $PATH#

exec: "buf": executable file not found in $PATH

Cause: Buf is not installed and APX couldn’t resolve it from the cache.

Fix:

apx fetch              # preferred — uses pinned version from apx.lock
# or
brew install bufbuild/buf/buf   # install system-wide

Git & GitHub Errors#

gh: not authenticated#

Error: gh: not authenticated. Run "gh auth login" to authenticate.

Cause: The GitHub CLI is not authenticated, required for apx release submit.

Fix:

gh auth login

permission denied when pushing#

Error: remote: Permission to org/apis.git denied

Cause: Your credentials don’t have write access to the canonical repo.

Fix:

  • For local releases: ensure you have push access to the canonical repo

  • For CI: verify the GitHub App is installed and org secrets (APX_APP_ID, APX_APP_PRIVATE_KEY) are set

could not determine org and repo#

Error: could not determine org and repo.
Either create an apx.yaml or ensure a git remote named 'origin' is configured.

Cause: No apx.yaml found and git remote detection failed.

Fix: Run apx init app --org=<org> --repo=<repo> ... or ensure a git remote named origin exists.

Dependency Errors#

Module not found in catalog#

No results found for "nonexistent-api"

Cause: The API doesn’t exist in the catalog, or the catalog is out of date.

Fix:

  • Verify the API ID with apx search

  • Run apx catalog generate in the canonical repo to refresh the catalog

Exit Codes#

Code

Meaning

Common triggers

0

Success

—

1

General error

Schema validation failure, release error, tool not found

6

Config validation error

Invalid apx.yaml

See Also#

Contents