Troubleshooting
If the venue gate or the attestation refuses, nothing was sent. A step that was slow or cancelled may already have sent the paper to your model backend. This page lists what can go wrong, in the words you would use, and what to do about it.
How a refusal reaches you
Section titled “How a refusal reaches you”A step that runs in your private view shows the full message there. That covers the review, a draft, a note, the triage list and model access. In pi the message opens in pi’s own view. In the other agents it shows in the review window, under “Refused”.
A step with no private view, such as starting a session, leaves you with
a short code, such as changed-input. The agent reports it to you.
refereekit never gives the agent the full message, because it can name a
file or quote one.
Each code also carries a fixed next step for the agent, so the agent already knows what to do or what to ask you. The same table that gives the agent its next step gives this page its situations, so the two always agree.
Situations
Section titled “Situations”The review window does not open
Section titled “The review window does not open”refereekit shows your paper and your drafts only on your own screen. Run your agent in a desktop session on the computer in front of you, with a text editor installed.
The language model is not set up
Section titled “The language model is not set up”Ask your agent to open model access. Choose your deployment, enter its key, and confirm that your account keeps nothing. The key never goes through the chat.
Your venue forbids outside models
Section titled “Your venue forbids outside models”refereekit sent nothing. If the venue’s rule has changed, edit venue-policy.toml in your reviews folder yourself. Otherwise review this paper without a model.
No venue was named
Section titled “No venue was named”Tell your agent which journal or conference the review is for.
The agent named a session that is not there
Section titled “The agent named a session that is not there”Ask your agent to list your sessions and pick the one you mean.
The session was deleted
Section titled “The session was deleted”A deleted session cannot be restored. Start a new review on the PDF.
The session holds a different paper, or none
Section titled “The session holds a different paper, or none”Start a new review on the PDF. The old session stays until you delete it.
The PDF cannot be read
Section titled “The PDF cannot be read”Check that the file exists and opens in your PDF reader. A scanned PDF has no text refereekit can check.
A link or a path outside the review
Section titled “A link or a path outside the review”refereekit edits and deletes only inside your reviews folder. Replace any symbolic link there with the real folder or file.
This is not a reviews folder
Section titled “This is not a reviews folder”Open your agent in your reviews folder. If you have none yet, paste the setup prompt and your agent makes one.
A settings file is not valid
Section titled “A settings file is not valid”Open refereekit.toml or venue-policy.toml in your reviews folder and undo the last change you made to it.
The agent tried to pass your words
Section titled “The agent tried to pass your words”Type questions, verdicts, notes and keys only in refereekit’s own window. The agent opens it for you.
The agent made a call refereekit refused
Section titled “The agent made a call refereekit refused”Nothing happened. Ask the agent to try the step again.
Nothing to draft yet
Section titled “Nothing to draft yet”Ask your agent to open the review, and ask your questions there. Drafts are written only from answers that were checked.
OpenReview did not answer
Section titled “OpenReview did not answer”Check your OpenReview account in model access, then ask again. If OpenReview is down, wait and try later.
The OpenReview form or replies are missing
Section titled “The OpenReview form or replies are missing”Ask your agent to fetch the submission from OpenReview first.
Keep or discard your venue notes
Section titled “Keep or discard your venue notes”Before a session is deleted, choose whether to keep its venue notes in a notes file outside the session, or to discard them.
A session cannot be deleted safely
Section titled “A session cannot be deleted safely”Nothing was deleted, because refereekit could not read what deleting would destroy. Keep the session, and ask your agent to run refereekit’s checks.
You edited a draft
Section titled “You edited a draft”Choose in refereekit’s window whether to replace it. Your edited copy is kept either way.
A note holds the paper’s words
Section titled “A note holds the paper’s words”Rewrite the note in your own words. refereekit never stores text from a manuscript under review.
Your agent or system is not supported
Section titled “Your agent or system is not supported”Install or upgrade your agent to the version refereekit names, on a supported system, then ask your agent to set refereekit up again.
A refereekit file in your folder was edited
Section titled “A refereekit file in your folder was edited”Decide whether to keep your edited copy. refereekit replaces it only when you say so.
The starter question list is not valid
Section titled “The starter question list is not valid”Ask your agent to show the question templates and choose again. Questions about one paper go in that session’s own questions file.
A step is busy, slow or cancelled
Section titled “A step is busy, slow or cancelled”Wait for the step that is running to finish, then ask again. A lower effort in model access makes a slow draft quicker.
refereekit needs repair
Section titled “refereekit needs repair”Ask your agent to upgrade refereekit and update your reviews folder. It asks your approval before each step.
refereekit does not start in pi
Section titled “refereekit does not start in pi”refereekit is installed, but pi cannot find it, most often because uv’s tool folder is not on the PATH. uv’s installation page says how to add it. Then close pi, open a new window and start pi again.
refereekit stopped with an internal error
Section titled “refereekit stopped with an internal error”Nothing of your paper was shown. Ask again; if it fails again, ask your agent to upgrade refereekit.
Results that are not errors
Section titled “Results that are not errors”Some results look like faults but are the checks working as designed.
A quotation you know is right comes back FLAG. You quoted fewer
than four words. A phrase that short is never checked, so only its page
is. Quote more of the sentence. See Floors.
An equation the paper has comes back FAIL. refereekit records an
equation’s label only when it can see the label printed beside a
displayed equation. The FAIL never says the paper lacks the equation.
See Extraction limits.
A figure the paper has comes back FAIL. Its caption may be written
“Figure 3:” rather than “Figure 3.”, which refereekit does not read.
A draft carries flags. The draft cites something your questions never established, or its words for a page do not check out. See The two draft flags.
The finishing checks pass. A clean finish means nothing is missing and nothing fails. It is not approval of the report.
A draft is slow
Section titled “A draft is slow”A draft through the claude-cli deployment stops at its 30-minute limit.
Choose a lower effort in model access, and the next draft is quicker.
When nothing here fits
Section titled “When nothing here fits”Ask your agent to run refereekit’s checks of your machine. It reports what is missing without sending anything. If that finds nothing, ask the agent to upgrade refereekit and update your reviews folder. It asks your approval before each step.
If you report a problem, describe what you did and give the code. Never include the paper’s words, a draft, or a file from a session.
See also
Section titled “See also”- What verification means: what each verdict promises.
- Confidentiality: the venue gate and the attestation.
- Reviewing in your coding agent: each agent’s private view, and what it protects.