Troubleshooting

Docket’s refusals are written to be acted on: each says what is wrong and names a way out. This page lists them by the message you or your agent will see.

The adapter will not start

No API key

[docket] DOCKET_API_KEY is not set. Get a key at https://app.usedocket.dev and add it
        to this server's "env" block in your MCP client config.

Why. The adapter has no key, so it stops before your client can use it.

What to do. Make a key on the keys page and put it in the adapter’s env in your client’s configuration. The quickstart has the command for each client.

Every call is refused

The key is rejected

Docket rejected the API key. Check DOCKET_API_KEY, or issue a new key at https://app.usedocket.dev/keys

Why. The key is not one Docket knows: it was mistyped or cut short when pasted, it has been deleted, or the account it belonged to has been deleted.

What to do. Make a new key and replace the old one in your client’s configuration, then restart the client. A key is shown once, when it is made; Docket keeps no copy it could show you again.

The adapter is out of date

Your @usedocket/mcp speaks protocol 1; this server needs 2 or later. Update with: npx -y @usedocket/mcp@latest

Why. The adapter on your machine is older than the server can work with. This happens when a tool the server now relies on did not exist in your version.

What to do. Restart your client so that npx -y @usedocket/mcp@latest fetches the current adapter. If your configuration names a fixed version, change it.

Too many requests

Too many requests: more than 300 a minute for this account. Wait 12 seconds and try again.

Why. An account may make 300 calls a minute across all its keys, with up to 60 at once. The reply carries a Retry-After header with the same number of seconds.

What to do. Wait that long. An agent in a loop that is calling Docket this often is usually retrying something that will not succeed; read the refusal it is retrying.

A second limit applies to a key that does not authenticate: ten attempts a minute, after which that key is told Too many requests with an API key that has not authenticated. Fix the key; waiting will not.

A refusal that counts calls made today, not in the last minute, is a ceiling: see A ceiling.

Docket cannot be reached

Could not reach Docket at https://app.usedocket.dev. Check your connection.
Docket did not respond within 10s. Retry shortly.

Why. The first is your network, or the server being down. The second is the server being slow.

What to do. Try again. Nothing was changed by a call that got no answer.

Over a limit

Too large

goal is 41 KB; the limit is 32 KB.
scope_globs has 240 entries; the limit is 200.
That is 70 KB in all; the limit is 64 KB.
APP-215 already depends on 200 cards; the limit is 200.
This request is over 256 KB, which is the most Docket reads.

Why. What one call can write is bounded: a field at 32 KB, a list at 200 entries, the dependencies written on one card at 200, and one card, note or report at 64 KB in all. The server reads no request over 256 KB. The message names what was too big, by the argument’s own name. Nothing is written by a call that is refused. The files a finish reports as changed are never refused: a long list is stored shortened.

What to do. Shorten it. Long material belongs in the repository, with a pointer to it on the card. One glob covers many files, so a long list of paths can usually be a few patterns. For dependencies, depend on the last card of a chain, not on every card in it.

A ceiling

This account holds 10,000 cards, and Pro allows 10,000; deleted ones count until they are removed. Remove old cards at https://app.usedocket.dev/account. Moving to Scale lifts it, on request: https://app.usedocket.dev/billing.
This account has made 5,000 calls today, and Pro allows 5,000 a day. Calls are refused until midnight UTC, in 3 h 12 min. Moving to Scale lifts it, on request: https://app.usedocket.dev/billing.

Why. An account has four ceilings, set by its plan, and the message names the plan and its number:

• Calls a day, across all its keys.
• Log entries a day: what its agents and its people write. What Docket writes for itself, such as a lease running out or a merge being seen, is never counted.
• Cards, every one it holds. Deleted cards count until they are removed.
• Projects in use. Archived ones do not count.

A day is a UTC day. An account that has never subscribed has the Pro plan’s ceilings. A ceiling refuses the write; it never charges for it. On the board, the same sentence appears where you made the change.

What to do. Your agent is told to pass the message on to you and not to retry. For a day’s ceiling, the count starts again at midnight UTC. For cards, remove old ones on the account page. For projects, archive one on the board. The message also says which plan lifts it.

Claiming

No cards ready

no cards ready: 2 blocked on dependencies, 1 waiting on files held elsewhere, 0 orphaned and needing repair, 1 in progress

Why. Nothing on the board can be started right now. The numbers say what each card that is to do is waiting for.

What to do. It depends on which number is not zero.

• Blocked on dependencies: finish the cards they depend on. list_cards shows what each one waits for.
• Waiting on files held elsewhere: another card being worked on holds a file. Claim the waiting card by name to be told which file and which card.
• Orphaned: see Orphaned below.
• In progress, and nothing else: the work is all claimed. Wait, or add a card.

If every number is zero, the board is empty or finished: create a card.

Already claimed

APP-215 is not claimable: already claimed by another agent

Why. A card has one holder, and this one has one.

What to do. Claim a different card. If the agent that holds it has stopped, the card comes back by itself when its lease runs out, 30 minutes after that agent’s last call. You can also take it back at once from the card on the board. See The life of a card.

Blocked on dependencies

APP-216 is not claimable: blocked on incomplete dependencies: APP-214, APP-215

Why. The card depends on cards that are not done. The message lists them.

What to do. Do those first; claim_next with no arguments will hand them over in order. If the dependency is wrong, remove it with unlink_cards.

Waiting for a merge

APP-216 is not claimable: waiting for APP-214 to merge. Docket ordered this card after it because both
write the same files, and starting before the merge would branch from a base without that work. Once the
pull request is merged and this checkout has fetched it, the next claim sees it. If the order is wrong,
unlink_cards removes it for good

Why. Docket put this card after another because both change the same file, and the other one is done but its work is not on your main branch yet.

What to do. Merge the other card’s pull request, then git fetch (or git pull) in the checkout your agent is using, and claim again. Docket sees a merge only once that checkout has it, and only if the merged commits carry the card’s Card-Id trailer. If the two cards do not really collide, remove the order with unlink_cards.

Files held by another card

APP-216 is not claimable: its files are held by work in flight:

Why. The card names a file that a card being worked on already holds. The message names the file and the card.

What to do. Wait for that card to finish. Or, if this card should always follow it, say so with link_cards, which puts the order on the board.

Orphaned

APP-217 is not claimable: orphaned — it depends on APP-210 (deleted). Drop that edge with unlink_cards,
or re-point the card with link_cards, then claim it again

Why. A card this one depends on was deleted, so the dependency can never clear.

What to do. What the message says: remove the dependency with unlink_cards, or replace it with link_cards. The card returns to to do by itself.

Working in a worktree

This project runs one card per worktree, and this session is in the main checkout. Start an agent in its
own workspace and claim APP-215 from there:

Why. The project requires each card to be done in a git worktree of its own, and the adapter was started in the main checkout. Nothing was claimed.

What to do. Run the command the message gives, and start your agent in the directory it makes.

If the agent is in a worktree and still sees this, the adapter is reading git from where your client started it, not from where the agent is. Have the agent pass the worktree’s path as workdir to claim_next, and to finish_card, claim_files and add_note after it.

While working

The claim is not valid

claim 66 is not valid for APP-215. It may have expired, been released, or belong to another card — re-claim before reporting.

Why. The claim token no longer holds the card. Most often the lease ran out: the agent made no call about the card for 30 minutes, and the card went back to to do.

What to do. Claim the card again with claim_next and its name, and use the new token. The work in the repository is untouched. On a long task, leave a note with add_note now and then: any call with the token starts the 30 minutes again.

Files cannot be taken yet

APP-216 cannot take those files yet:

Why. claim_files was asked for a file that another card being worked on holds.

What to do. Do not edit the file. Wait for the other card, or make this card depend on it with link_cards. This is the moment asking first pays for itself: nothing has been changed that has to be undone.

A pattern given to claim_files

claim_files takes literal file paths, not globs:

Why. A path given to claim_files had a * in it. Docket cannot list the files a pattern matches.

What to do. Name each file. To widen what the card may touch in general, change its scope with update_card.

Finishing

Finishing is refused

Why. The project has git rules and the work does not meet them yet: it is on the wrong branch, the branch is not pushed, or there is no pull request. The message names each missing step, or the one command the project uses for all of them.

What to do. Do what it lists, then call finish_card again with the same token.

Deleting

The card has dependents

APP-214 has 2 live dependent(s); use orphan mode to delete anyway

Why. Other cards depend on the one being deleted.

What to do. Either re-point or unlink those cards first, or delete with mode: "orphan", which deletes the card and leaves the others orphaned for you to repair.

Cascade delete

cascade delete is not permitted on this surface

Why. Deleting a card together with everything that depends on it is only offered on the board, where a person confirms it.

What to do. Do it from the board.

Outside a git repository

There is no refusal for this. In a directory that is not a git repository, or one with no origin remote, the adapter still works, but:

• Cards go to a default project and not to one named for a repository.
• A finish carries no verified git facts, so the card cannot be seen as merged.
• Rules about files still apply, since they come from the card’s scope.

If you expected a repository’s own board and got an empty one, check that the client starts the adapter inside that repository.

The code behind each message

Refusals from the board carry a code. Your agent sees the message; the code is for telling them apart.

Code	Meaning
DK001	No card is ready.
DK002	That card cannot be claimed.
DK003	The claim token is stale or wrong.
DK004	The card has dependents and cannot be deleted as asked.
DK005	Cascade delete is not offered here.
DK006	No such card.
DK007	A file is held by another card, or claim_files was given a pattern.
DK008	Too large to store: see Too large.
DK009	Over one of the account’s ceilings: see A ceiling.