Common errors
Exit-code-driven troubleshooting — auth failures, ambiguous names, copy fallback, offline sync, and orphaned skills.
Every command exits with a code that tells you what class of problem you hit, and
--json failures return a structured error. This page maps the common situations
to their cause and fix.
Exit codes at a glance
| Code | Class | Typical cause |
|---|---|---|
0 | OK | Success. |
1 | User / validation | Bad input, ambiguous ref, invalid arguments. |
2 | Auth | Not logged in, or not authorized for the action. |
3 | Network | Offline, transport failure, retry later. |
4 | Integrity / scan | Blocking scan finding, or a content-hash mismatch. |
With --json, a failure returns { ok: false, error: { code, message, details? } }
on stdout — read message first.
Not logged in (exit 2)
Publishing, or any registry action, requires authentication. If you see an auth error, confirm who you are and log in:
skillhub whoami
skillhub loginIn CI, the browser login flow can't run. Use a token instead — either
login --token or the token environment variable. See
API tokens.
Ambiguous short name (exit 1)
A bare skill name has to resolve to exactly one skill across your configured registries. If the same name exists in more than one, the command fails as ambiguous. Fix it by using the fully qualified ref:
skillhub install @studio/design-systems/tokens-workflowSymlinks unavailable — copy fallback
Skills install once into a canonical store and fan out to each agent by
symlink. On platforms without symlink support, SkillHub automatically
falls back to copying and prints a notice — nothing fails. You can also opt
into copying everywhere with --copy.
Copied skills show up in skillhub list with copyMode: true. This is expected
behavior, not an error.
Offline sync — tolerated or exit 3
skillhub sync normally uses the network to resolve your subscription set. Run it
offline and the outcome depends on what's already on disk:
- If the lockfile is already satisfied on disk, sync warns that it's offline and
exits
0— there's nothing to reconcile, so being offline is tolerated. - If the lockfile cannot be reconciled offline — a resolve is genuinely
needed — sync changes nothing rather than guessing and exits
3. Reconnect and run it again:
skillhub syncIn CI, sync --frozen fails with exit 1 if the lockfile would drift. That's by
design — it tells you the committed lockfile is out of date, not that anything is
broken.
Orphaned skills after revoked access
If a registry is deleted, or your access to it is revoked, its skills stay on
disk but are marked orphaned in skillhub list. They're no longer backed
by a reachable subscription. Clear them out with a pruning sync:
skillhub sync --pruneDeletion always requires --prune — a plain skillhub sync keeps orphaned
skills on disk and only warns, so nothing disappears from under you by accident.
Drift and integrity (exit 4)
Exit 4 also covers a content-hash mismatch — the bytes on disk don't match the
version they claim to be. Run skillhub doctor to locate the drift and follow its
fix:
skillhub doctor