CLI errors

#internal

Something failed that nothing on this page covers. Two different things print this, and the message tells you which: a local crash is prefixed `unexpected error:` and exits 1; a server failure carries the server's own sentence and exits 3.

The local half is the catch-all at the top level — most often an environment problem (a Node version below 18, a broken install) rather than anything about your account or the skill. The server half is deliberately redacted: the real cause is database or provider text that stays server-side, so the sentence you get is generic BY DESIGN and there is nothing further to read into it.

Fix

• Check your Node version: `node -v` — the CLI needs 18 or newer.
• Reinstall: `npm i -g promptdock@latest`, or run via `npx promptdock@latest`.
• If it exited 3 with a server message, retry once — a redacted 500 is often transient and nothing was installed.
• If it repeats, capture the exact message and `promptdock --version` before anything else — that pair is what makes it diagnosable.

#usage

The arguments did not make sense for that command.

Most often: a non-interactive run (CI, a pipe) without --target/--dir and -y, which the CLI will not guess at.

Fix

• npx promptdock@latest --help
• In CI, pass --target, --dir and -y explicitly.

#login_timeout

The pairing code was not approved before it expired.

Codes are short-lived on purpose — an unclaimed code should not stay valid.

Fix

• npx promptdock@latest login

#auth

There is no stored token, or the one on disk was rejected.

Tokens are per machine and can be revoked from the dashboard or by `promptdock logout`.

Fix

• npx promptdock@latest login
• Or set PROMPTDOCK_TOKEN in CI.

#upgrade_required

Your CLI is older than something the server needs. Two different things produce this, and they differ in blast radius: either ONE package is too large for the safety limits built into your version — everything else keeps working — or your CLI is below the minimum version the API accepts at all, in which case every command fails, including login.

The CLI carries its own install-safety limits so a compromised server cannot fill your disk or write outside the target directory. Those limits are fixed at the version you installed, so a package published above them needs a newer CLI — and only that package is refused. Separately, the API enforces a minimum CLI version for wire-breaking changes; a client below it is rejected before it authenticates, so that refusal is account-wide, not package-scoped. The error text tells you which one you hit: a named skill means the first, a minimum-version number means the second.

Fix

• npx promptdock@latest install <handle>/<slug>
• If you installed globally: npm i -g promptdock@latest
• In CI, unpin the version or raise the pin to the version named in the error.
• If you cannot even log in, it is the account-wide floor — upgrade first, then run `promptdock login`.

#insufficient_tier

The skill's contents are available on a paid plan and your account is on a lower tier.

Premium skills unlock by subscription, not per item.

Fix

• https://promptdock.ai/pricing
• Free skills install with no plan at all.

#cap_hit

You have unlocked the maximum number of distinct premium skills in a rolling 24-hour window.

The cap counts distinct skills, not installs. Re-installing something already unlocked does not count again.

Fix

• Wait for the window named in the error.
• Skills you have already unlocked keep installing.

#not_found

The ref did not resolve to a skill you can see.

Either the ref is wrong, or the skill is a draft, unlisted, or has been taken down.

Fix

• The format is handle/slug — for example: npx promptdock@latest install alice/seo-audit
• A pasted promptdock.ai skill URL also works.
• Check the account: npx promptdock@latest whoami

#account_disabled

The account behind your token is disabled, so every command fails — not just this one. Nothing was installed.

Disabling is a soft delete with a 90-day recovery window: your skills, installs and content all survive, but API access is cut immediately on the shared gate every route runs. The token is not the problem and re-running `login` will not help — a fresh token on a disabled account is refused the same way.

Fix

• Recover it in a browser: https://promptdock.ai/account/recover
• After 90 days the account and its data are purged and there is nothing left to recover.
• If you did not disable it, sort that out in the browser before re-running anything here.

#version_conflict

A new version was approved in the seconds between the CLI resolving the skill and asking for its files. Nothing was downloaded or written.

Install pins the exact version resolve returned and the server serves that one or refuses. It will not quietly substitute the newer version, because a package assembled from two versions is a worse outcome than a failed command — and you would have no way to tell it had happened.

Fix

• Re-run the same command — the second attempt resolves the new version and installs it.
• Nothing on your side caused this: the author shipped an update at that moment.
• In CI, treat this footer as retryable — one retry is enough unless the skill is being republished in a loop.

#conflict

The server refused because the record it was asked to create already exists.

It is the generic uniqueness refusal (a database unique-violation, surfaced as a 409). From the CLI the usual cause is two runs racing each other on the same account — parallel CI jobs installing the same skill at the same instant.

Fix

• Read the message above: it is more specific about what already existed than this page can be.
• Retry once — if the existing record is the one you wanted, the retry succeeds.
• In CI, do not install the same skill from two jobs concurrently.

#validation_error

Something the CLI sent was not a shape the server accepts. Nothing was installed.

Two causes, and the message above distinguishes them. Either the input was wrong — a ref that is not `handle/slug`, an id that is not a UUID — or your CLI is older than the request shape the server now expects, in which case every run of that command fails identically.

Fix

• Check the ref: it is handle/slug, e.g. npx promptdock@latest install alice/seo-audit
• A pasted promptdock.ai skill URL also works — the CLI parses it.
• If the input is right, run it through the latest CLI: npx promptdock@latest install <handle>/<slug>

#not_owner

The server refused the read or write behind this command for the account your token belongs to.

Row-level security denied it. From the CLI the overwhelmingly likely cause is being signed in as an account you did not mean to use — a token is per machine, so the one on this machine may not be the one you have open in the browser, and nothing prints the account until you ask.

Fix

• Check which account this machine is using: npx promptdock@latest whoami
• If it is the wrong one: npx promptdock@latest logout, then npx promptdock@latest login
• In CI, check that PROMPTDOCK_TOKEN belongs to the account you meant to use.

#service_unavailable

An upstream dependency was unreachable or is not configured. Not your account, not the skill, and nothing was installed.

This is the one server-side failure the API does not redact: an operator-fixable state is something you are entitled to read plainly rather than as an anonymous crash, so the sentence above names it. No `/cli` route raises it today, so seeing it from the CLI means a shared dependency broke, not that you did anything unusual.

Fix

• Retry in a few minutes — it is transient by definition.
• Check https://promptdock.ai loads in a browser. If the site is up and this persists, it is a server configuration problem and there is nothing to fix from the CLI.
• In CI, treat this footer as retryable rather than a hard failure.

#mfa_required

An action was refused until two-factor authentication is completed.

CLI tokens are exempt from the second-factor challenge by design — the token was minted inside a browser session that had already passed it — so the terminal does not normally produce this. Where it does reach CLI users is the browser half of `login`: with an authenticator app enrolled, the approval page asks for a code first, and until you enter it the terminal keeps counting down with no explanation for the wait.

Fix

• Finish the authenticator prompt in the browser, then approve the pairing code.
• If the countdown already ran out, start over: npx promptdock@latest login
• If this reached the terminal itself, it is a server-side problem — capture the message and `promptdock --version`.

#access_denied

The browser approval for this CLI session was denied.

Someone chose Deny on the device-approval screen, or approved a different code.

Fix

• npx promptdock@latest login
• Check the code in the browser matches the one in your terminal.

#verdict

The server answered with a decision this CLI does not know how to act on.

The server is newer than the CLI.

Fix

• npx promptdock@latest install <handle>/<slug>

#rate_limited

The API asked you to slow down. Nothing was installed or changed.

CLI routes are rate limited per account and per IP. The per-IP half is the one that surprises people: several developers behind one office NAT, or a CI fleet on shared egress, share a bucket even with different accounts.

Fix

• Wait for the period named in the message, then retry.
• In CI, stagger parallel jobs rather than starting them in one burst.
• If you are behind a shared NAT with colleagues, that is the likely cause — it is not your account alone.

#api

A request failed. Usually the server explained why in the message above this footer — but if you were told the response redirected somewhere unexpected, nothing reached the server at all.

For an ordinary failure the server's own message is more specific than anything this page can say. For the redirect case the CLI refuses to follow a cross-domain or non-https hop, because a captive portal or a MITM can mint one — so it stops rather than sending your token onward.

Fix

• Read the message above — for an ordinary failure it is the most specific thing you have.
• If it mentions a redirect: check PROMPTDOCK_API_BASE, and whether you are behind a captive portal or a corporate proxy.
• Retry if it looks transient. If it is a skill-content problem, report it from https://promptdock.ai/dashboard/skill/r/<handle>/<slug> — that needs a sign-in, because Report lives on the dashboard page, not the public one.

#not_installed

`update` or `uninstall` found no promptdock receipt in that directory.

The CLI only manages directories it installed, identified by `.promptdock.json`.

Fix

• npx promptdock@latest list
• Then re-run against a directory that appears in it.

#no_receipt

`list` or `update` scanned the known locations and found no receipts.

Either nothing is installed, or it was installed somewhere the CLI does not scan.

Fix

• Point at it explicitly: --dir ./path
• Or install one: npx promptdock@latest install <handle>/<slug>

#manifest_bounds

The server returned a file list larger than this CLI will ever install. Nothing was downloaded or written.

This is the untrusted-server backstop, not a policy limit. You would normally see the friendlier `upgrade_required` refusal before any download starts. Reaching this one means the response did not match what the CLI asked for.

Fix

• Update: npx promptdock@latest install <handle>/<slug>
• If it persists on the latest CLI it is a server bug, not a package problem — capture the exact message and `promptdock --version`.

#manifest_path

A file had a path the CLI refuses to write — a traversal segment, an absolute path, a backslash, a control character, or a Windows reserved name. Nothing was written.

The CLI re-validates every path itself so a compromised server cannot turn an install into an arbitrary file write. It never trusts the server's validation.

Fix

• There is no workaround, by design — do not retry with one.
• A published package should never contain such a path — report it so it can be taken down.
• Signed in, https://promptdock.ai/dashboard/skill/r/<handle>/<slug> resolves the ref onto that skill's page, where Report sits in the sidebar.

#integrity

A file's SHA-256 did not match the manifest. The install was abandoned and the staging directory discarded — existing files were not touched.

Every file is hashed after download and compared before anything is moved into place. A mismatch means the bytes changed in transit or at rest.

Fix

• Retry — a transient network fault is the usual cause.
• If it repeats for the same skill, report it: signed in, https://promptdock.ai/dashboard/skill/r/<handle>/<slug> resolves the ref onto that skill's page, where Report sits in the sidebar.

#receipt_schema

`.promptdock.json` in the target directory uses a schema this CLI does not understand, so it will not guess at an uninstall or update.

The receipt is the only record of which files an install owns. Acting on one it cannot read risks deleting files it does not own.

Fix

• npx promptdock@latest update
• Or remove the directory by hand if you no longer want the skill.

#receipt_invalid

`.promptdock.json` exists but is corrupt or missing required fields.

Without a valid receipt the CLI cannot tell which files it owns.

Fix

• Remove the directory by hand, then reinstall.
• npx promptdock@latest install <handle>/<slug>

#local_changes

Installed files no longer match the checksums in the receipt, so the update or uninstall stopped.

Overwriting would silently discard your edits. The CLI would rather stop than lose work you did on purpose.

Fix

• Copy your changes somewhere safe first.
• Then re-run with --force to overwrite.

#eacces

The CLI could not write to the install directory.

The directory is owned by another user, or is read-only.

Fix

• Choose a different location: --dir ./my-skills
• Or fix the permissions on the path in the message.

#enospc

The write ran out of space. The partial staging directory was discarded.

The CLI stages into a sibling directory and renames, so a full disk fails cleanly rather than half-writing.

Fix

• Free up space and retry.

#existing_dir

The target exists and is not a previous install of this skill.

The CLI will not merge into a directory whose contents it does not own.

Fix

• Install elsewhere: --dir ./somewhere-else
• Or overwrite deliberately: --force

#io

A read or write failed for a reason the CLI could not classify.

The underlying error is printed in the message above, and it names the path.

Fix

• Read the message above.
• Retry, or choose a different --dir.

#config

`~/.promptdock/config.json` could not be read, written, or locked down to owner-only permissions.

The config holds your API token. If the CLI cannot set 0600 on it, it refuses to keep the token rather than leave it world-readable.

Fix

• Check ownership and permissions on ~/.promptdock/
• Or use PROMPTDOCK_TOKEN instead of a stored token.

#network

The request never got a response.

Usually connectivity. Note that Node's built-in fetch does NOT read HTTPS_PROXY / HTTP_PROXY — behind a corporate proxy, requests fail even though curl works.

Fix

• Check your connection, then retry.
• Behind a proxy, run on a network that does not require one — the proxy env vars have no effect.
• Check https://promptdock.ai loads in a browser.

#download

One of the package's files failed to fetch. Nothing was installed.

Download URLs are short-lived; a slow or interrupted install can outlive them.

Fix

• Retry — a fresh set of URLs is issued each time.