Errors

How errors look

Without --json, on stderr:

$ shelf return pdf-tools
error: The project copy of "pdf-tools" has local edits
hint: Keep them with `shelf promote pdf-tools` or `shelf detach pdf-tools`, or discard them with --force

With --json, one line on stdout:

{"schemaVersion":1,"ok":false,"error":{"code":"NOT_BORROWED","message":"\"nope\" is not borrowed by storefront","hint":"Run `shelf borrow nope` first"}}

hint is null when there is nothing more specific to say than the message.

Codes

INTERNAL (exit 1) is not a shelf error code but what the CLI reports for anything unexpected: a bug, a full disk. The message is the underlying error; text output adds a stack trace. Please report reproducible ones.

What to do

INVALID_ARGUMENT

An argument, option or file shelf reads is not acceptable. Read the message; it names the value.

INVALID_SKILL

A SKILL.md isn't a valid skill: no frontmatter, invalid YAML, a name that doesn't match its directory, a missing or overlong description. It comes from commands that read a skill directory you point at (adopt, add, promote, restore, rename). Fix the frontmatter; shelf lint and Writing skills list the rules.

NOT_INITIALIZED

The working directory isn't inside a shelf project, and the command needs one (borrow, renew, return, sync, targets, suggest, …). Run the command inside the project, or shelf init in its root if it should start using shelf. Agents shouldn't run init unless asked.

SKILL_NOT_FOUND

No skill (or set) by that name. shelf catalog lists skills, shelf set list lists sets. Archived skills and library directories that aren't valid skills (see shelf doctor) count as not found, except to shelf lint, which reports why they don't load. shelf add --skill uses it for a name the source doesn't have; the hint lists what it has.

NOT_BORROWED

The project doesn't borrow that skill. shelf status lists its loans; shelf borrow <name> borrows it. shelf diff uses it when borrowed or project is asked for outside a project that borrows the skill.

SKILL_EXISTS

The name is taken: a library directory with that name exists (new, rename, duplicate), an archived skill had that name (new, rename, duplicate, add), or the skill is already linked to a source (add; use shelf pull). Choose another name, or restore the archived skill by moving it back from ~/.shelf/archive/.

CONFLICT

The operation would clash with state shelf doesn't own or can't reconcile on its own.

LOCAL_CHANGES

A project copy has local edits that the operation would discard: return, update <name>, or targets --remove. Keep the edits with shelf promote <name> (to the library) or shelf detach <name> (in the project), or discard them with --force.

LOAN_LIMIT

The due date would be more than maxLoanDays (90 by default) from now: borrow --days, renew, due or loan-days. The hint gives the latest allowed date or number of days. Use a shorter period, or raise maxLoanDays in the config. For a skill the project always needs, shelf keep is the alternative.

NOT_ALLOWED

An agent tried to import a skill from a git source (shelf add --yes of a new skill, or shelf pull --yes) while allowAgentImports is false. The agent should show you the review and the exact command, for you to run. See Importing skills.

Usage errors without --json

Without --json, an unknown command or a missing argument prints the command's help followed by the problem, and exits with code 2 (as with --json):

$ shelf new nod
…
Missing required argument: --description

Related

• CLI reference, Troubleshooting