Skip to main content

Troubleshooting

Most problems are a stuck run, a connector that needs re-adding, or a tool call the server refused on purpose. Find the symptom below, then report a reproducible bug only after the checks fail.

App and run problems

SymptomCheck
A run stays at a review gate. The run is waiting for you. Open the run, read the proposed scope, literature or hypotheses, and approve or request revisions. Nothing downstream starts without that decision.
A run fails partway. Copy the run id and the visible error, then retry once. A search or model provider outage can be temporary; a repeated failure at the same stage is worth reporting.
You cannot start another run. You may have reached the monthly allowance, the concurrency limit or the hourly start limit. Check the allowance panel and the reset date. Bring-your-own-key runs still follow the hourly limit.
An export is missing or empty. Exports are available after the report stage and only when the plan enables exports. If the button is enabled but the file is empty, retry once and report the run id.
A report looks thin. Check the search terms and eligibility criteria first. A narrow query or an over-strict date range can leave too few included studies.
Refresh before reporting

A reload can reconnect to a run that is still processing. Check the run list before starting a duplicate, which would consume another allowance unit.

Claude Science and MCP setup

The exact Claude Science steps are in the MCP reference and in CLAUDE_SCIENCE.md. The errors below come from that guide.

MessageCause and fix
this kernel's Python interpreter ... is not readable inside the sandbox The command points outside the connector's workspace folder. Use the bundle path from the Claude Science steps, not your own virtual environment.
Set "command" to node, npx or python3 ... You gave an absolute path to a Python that Claude Science does not provide. Use python3 for the local command connector.
can't open file ... Permission denied The bundle is not inside the connector workspace. Build it into .../workspaces/_mcp-citeproof/bundle.
Connector name rejected Names allow lowercase letters, digits and hyphens only. Use citeproof.
npx cannot find the package or Node is too old Install Node 18 or newer. The launcher installs uv automatically when it is missing; set CITEPROOF_NO_AUTO_INSTALL=1 only if you manage uv yourself.

Missing tools or failed tool calls

SymptomCheck
18 tools instead of 24 An older server process is still running. In Claude Science, remove the connector and add it again with the same command and environment; old code stays in memory until then. In other clients, restart the client. The current release exposes 24 tools.
No CiteProof tools at all Confirm the client can start a stdio server. For Claude Science, check that the connector command points at the built run.py and uses forward slashes. For npx, run the server by hand and check that it starts without an import error.
ok: false with an error This is a refusal, not a crash. Read the error: it names the argument or state to change. Nothing was saved for a failed write. See handling ok:false.
The review file is busy Another write holds the SQLite file. The server waits up to 30 seconds, then returns a retry message. Retry the same call; idempotent tools replace the earlier record instead of duplicating it.
Invalid paper_ref Use a DOI, pmid:<digits> or title:<title>|<year>. Use the same form for the same paper in every tool. Check that the DOI has no trailing punctuation.
A DOI is unverified The registry could not be reached. It is not the same as not_found. Retry later; never describe an unverified DOI as fabricated.
An export is cut off Very large reviews are truncated at 5000 screening decisions or claims. The result sets truncated: true. Export the JSON format or split the review record; do not assume the missing rows were checked.

Review data and storage

  • Review files. One SQLite file per review under CITEPROOF_MCP_HOME/reviews/, default ~/.citeproof-mcp. Copy that folder to back up your reviews. Removing the connector does not delete it; delete the folder yourself if you want the data gone.
  • Source text. The audit store keeps only the length and SHA-256 of supplied source text, not the text itself. Quotes and the check results are stored.
  • Network. Only verify_dois makes outbound calls, to Crossref and doi.org. All other tools work offline.

Report a reproducible bug

Search the issue tracker first, then open an issue with enough detail to repeat the problem:

  • The page or tool, and what you expected to happen.
  • The exact steps, in order, including the arguments you sent.
  • The full result, including ok and error if present.
  • The client and version, operating system, and the UTC time of the failure.
  • For app runs, the run id. For MCP, the review_id and the install path you used.

Remove API keys, access tokens, authorisation headers, webhook secrets and unpublished participant data before posting. Do not paste a full source text or a confidential review into a public issue.

Report a security issue privately through the security policy, never in a public issue. Contribution guidance is in CONTRIBUTING.md. Account, billing and data-deletion requests go through contact support.

Authoritative sources

When a guide and the code disagree, the code wins. These files are the source this documentation is written from: