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.

If it repeats, email [email protected] with the command and the exit code — the link pre-fills what to include.

#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. Three different things produce this, and they differ in what still works: ONE package is too large for the safety limits built into your version, and everything else keeps working; or installing and updating skills needs a newer CLI, while login, list and uninstall still work; 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. Installs and updates also have their own minimum: promptdock 1.2.1 and older can overwrite files you edited and delete files you added when they update a skill, so the server refuses those two commands for them. 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. The error text tells you which one you hit: a message that names a skill is the first, one that says "Installing and updating skills now needs" is the second, and "below the minimum supported version" is the third.

Fix

• npx promptdock@latest install <handle>/<slug>
• If you installed globally: npm i -g promptdock@latest
• `promptdock upgrade` updates your installed skills; it does not update the promptdock CLI. To update the CLI: npm i -g promptdock@latest (or use npx 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://www.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 recovery window (30 days for an account you close yourself): 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://www.promptdock.ai/account/recover
• That page shows the deletion date, to the minute in UTC. After it 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.

If you did not disable it, or the recovery page will not take it, email [email protected] with the command and the exit code — the link pre-fills what to include.

#account_suspended

Support has put a hold on the account behind your token, so every command fails — not just this one. Nothing was installed.

A suspension is not a deletion and not a closure: your skills, installs and content are all still there, and nothing is on a countdown. What it does mean is that the hold can only be lifted by the people who applied it, so there is no self-serve page for this one and a fresh token will be refused the same way.

Fix

• Write to support from the address on the account and ask what the hold is about.
• Do not create a second account to work around it; that is usually what the hold is for.

Always — a suspension can only be lifted by support, email [email protected] with the command and the exit code — the link pre-fills what to include.

#account_closing

You have started closing this account, so it will not take on anything new. Reading, downloading and settling what is already open all still work.

Closing is a wind-down you can leave at any time, so it deliberately stops short of cutting you off: you keep every action that helps you finish — withdraw what you are owed, cancel a challenge, stop a renewal — and lose only the ones that would give you something new to settle.

Fix

• If you have changed your mind, keep the account: https://www.promptdock.ai/dashboard/profile?tab=account
• If you meant to close it, finish the things it is waiting on; that page lists them.

#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://www.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.

If the site loads in a browser and this is still failing minutes later, email [email protected] with the command and the exit code — the link pre-fills what to include.

#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`.

If this reached the terminal itself rather than the browser approval page, email [email protected] with the command and the exit code — the link pre-fills what to include.

#reauth_required

A payout action was refused until you sign in again. This happens on the website, not in the terminal: no `/cli` route asks for it.

Creating a payout account or opening Stripe onboarding hands out a Stripe session that decides where your money goes, so it needs a sign-in from the last few minutes, not just a session that is still open. Members with an authenticator app confirm with a code from it.

Fix

• Follow the "Confirm it's you" prompt in the browser; the action resumes afterwards.
• If you are signed in as a different account, sign out and sign in as the account that owns the payouts.

#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>

If you are already on the latest CLI and still get this, email [email protected] with the command and the exit code — the link pre-fills what to include.

#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://www.promptdock.ai/dashboard/skill/r/<handle>/<slug> — that needs a sign-in, because Report lives on the dashboard page, not the public one.

If the message is not about a skill's contents and does not explain itself, email [email protected] with the command and the exit code — the link pre-fills what to include.

#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`.

If it persists on the latest CLI, email [email protected] with the command and the exit code — the link pre-fills what to include.

#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://www.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://www.promptdock.ai/dashboard/skill/r/<handle>/<slug> resolves the ref onto that skill's page, where Report sits in the sidebar.

If retrying does not clear it, a repeated checksum failure is a delivery problem rather than a bad package; email [email protected] with the command and the exit code — the link pre-fills what to include.

#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

A file the receipt lists no longer matches it, or a file of yours sits where the new version ships one, so the command stopped and changed nothing. From 1.2.2, install checks too and the refusal names each file with its reason (modified, conflicts, special); 1.2.1 checks only update and uninstall.

Replacing the folder would discard your work. From 1.2.2, files you only added are kept on install and update and never block; line endings alone do not count as an edit.

Fix

• Keep your work: move the listed files out of the folder, then run the same command again.
• Or discard those changes: add --force. From 1.2.2 it replaces the listed files and keeps every other file you added; 1.2.1's --force replaced the whole folder.

#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 install into a directory whose contents it does not own until you say so.

Fix

• Install elsewhere: --dir ./somewhere-else
• Or add --force. From 1.2.2, files with no receipt (what an uninstall leaves when you had added files) are kept unless the new version ships the same path; another skill's folder is replaced, and the CLI lists what it removed.

#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://www.promptdock.ai loads in a browser.

If other sites load and every retry still fails, email [email protected] with the command and the exit code — the link pre-fills what to include.

#download

One of the package's files failed to fetch, or the connection dropped while it downloaded. Nothing was installed.

Download links are short-lived, and a slow install can outlive them. From 1.2.2 the CLI refreshes expired links once by itself and names the file it was downloading when a connection drops. When the message says the download links expired, the CLI already refreshed them once and the new links expired too.

Fix

• Run the same command again: each run gets a fresh set of links.

If a fresh run keeps failing on the same file, email [email protected] with the command and the exit code — the link pre-fills what to include.