APM Troubleshooting and FAQ

This page mirrors the canonical exit-code contract from docs/apm-cli-contract.md in calab-ai/gh-calab and pairs each code with the most common cause and fix.

---

Exit-code map

Every gh calab command obeys this contract — CI should branch on exit codes, never on stderr text.

Code	Meaning	Most common causes	Fix
0	Success	—	—
1	General error	Unhandled exception, network blip, malformed remote response	Re-run with --json and read stderr; file an issue if reproducible
2	Usage error	Bad arguments, unknown flag, unrecognised id shape	gh calab apm <subcmd> --help
3	Not found	Missing apm.yml / apm.lock.yaml, package or ref doesn’t exist in registry	Run gh calab workspace init, or check the id with gh calab apm catalog
4	Validation error	Manifest fails schema, primitive id pattern wrong, kind mismatch in install --kind/subcommand	See Validation errors below
5	Conflict	Lockfile drift, untracked file would be overwritten by sync, manifest/lockfile out of sync	gh calab apm resolve && gh calab apm sync (see Upgrading → drift)
6	Policy violation	Dependency blocked by org allowlist, branch ref used in production manifest	Switch to a tag ref or get the source repo added to the org allowlist
7	Auth error	gh not logged in, missing repo scope on calab-ai org	gh auth login, then gh auth refresh -h github.com -s repo

---

Common errors

Validation errors

Primitive id doesn’t match the regex

Error: id 'calab.skill.AzCli' violates primitive id pattern
       ^[a-z][a-z0-9]*\.(agent|instructions|prompt|skill|hook|init)\.[a-z][a-z0-9-]+$
Exit: 4

• Use kebab-case, never camelCase or snake_case.
• The middle segment is singular (agent, not agents) — the directory uses the plural form, the id uses the singular form.

Type doesn’t match the directory

Error: primitive 'calab.skill.az-cli' declares type 'instructions' but lives in primitives/skills/az-cli
Exit: 4

• Fix type in apm-primitive.json to match the directory under primitives/.

Package primitive ref shape

Error: package primitive ref 'agents/build' must match
       ^primitives/(agents|instructions|prompts|skills|hooks|init)/[a-z][a-z0-9-]+$
Exit: 4

• Refs in apm-package.json are registry-relative paths, not ids: primitives/agents/build, not calab.agent.build.

Kind mismatch on explicit install

Error: 'calab.skill.az-cli' is a primitive id but install was invoked as 'package'
Exit: 4

• Use the matching subcommand: gh calab apm install primitive calab.skill.az-cli.
• Or drop the assertion: gh calab apm install calab.skill.az-cli (auto-detect).

Lockfile drift (exit 5)

Error: apm.lock.yaml does not match apm.yml
       3 dependency entries differ; run 'gh calab apm resolve'
Exit: 5

Always solved by:

gh calab apm resolve
gh calab apm sync

If CI keeps failing, it is almost always because someone edited apm.yml and forgot to commit the regenerated apm.lock.yaml.

Tag conflict (publishing)

Error: tag refs/tags/primitives/skills/az-cli/v1.0.0 already exists
Exit: 5

• Pull the latest tags: git fetch --tags origin.
• Inspect existing versions: git tag -l "primitives/skills/az-cli/*".
• Bump version in apm-primitive.json past the highest existing tag and amend.

Branch refs rejected (exit 6)

Error: dependency 'calab.package.workspace-base' uses branch ref refs/heads/main
       branch refs are not permitted (set policy.allow_branch_refs: true to override in dev only)
Exit: 6

• Replace refs/heads/main with a real tag (e.g. refs/tags/packages/calab-workspace-base/v1.0.0).
• Only set policy.allow_branch_refs: true in development manifests, never in main.

Auth errors (exit 7)

Error: gh CLI is not authenticated, or lacks 'repo' scope on calab-ai
Exit: 7

gh auth login
gh auth refresh -h github.com -s repo
gh calab doctor

---

FAQ

Why do ids use agent (singular) but directories use agents (plural)?

The id namespace was designed before the directory layout. The plural directory matches schema-enum convention (type is a category) and the singular id reads more naturally as a reverse-domain noun (calab.agent.build ≈ “the build agent in the calab namespace”). Both shapes are pinned by their respective regex patterns and won’t change.

Can I depend on a primitive at a specific version?

Today, packages compose primitives by path, not version — primitive versions are pinned by the catalog snapshot. If you need a non-catalog version of a primitive, depend on it directly in apm.yml with an explicit source.ref. A future schema revision may add per-primitive version pinning inside packages.

Can I install from a fork or private mirror?

Only if the source repo is on the org allowlist. The resolver enforces the allowlist; you cannot bypass it from apm.yml. Get the source added via docs/apm-source-policy.schema.json update in calab-ai/apm-registry.

What if I edit a generated file by hand?

Don’t. The next apm sync will overwrite it — that is the whole point of .generated-from-apm.json. If you need to deviate, copy the file to a non-managed path and edit there, or open a PR to the upstream primitive.

How do I uninstall everything cleanly?

gh calab apm uninstall calab.package.workspace-base
# repeat for each dependency, or remove them en masse from apm.yml then:
gh calab apm resolve
gh calab apm sync

apm sync removes only files previously recorded in .generated-from-apm.json, so untracked files are safe.

gh calab apm publish doesn’t work

Correct — see Publishing → status. The publish subcommands are not yet shipped. Use the manual PR + semantic-release flow.

Where do I report bugs?

• CLI bugs and feature requests: calab-ai/gh-calab/issues.
• Schema, primitive, or package issues: calab-ai/apm-registry/issues.
• Marketplace portal issues: same registry repo (the portal is generated from portal-data.json).

---

Related

• Installing
• Upgrading
• Concepts
• CLI contract: gh-calab apm-cli-contract