Troubleshooting

This page lists the PRIMA Scholar problems that the product’s own code and release notes describe, grouped by where you meet them. Each entry gives what you see, why it happens and what to do. Error messages appear as Claude reports them, and Claude may show them inside a longer message that starts Scholar search error or Library error.

Installation and Start-Up

The Servers Are Missing After a Plugin Install

Symptom. /mcp does not list prima-scholar-search or prima-scholar-library, or lists them as failed. Requests for a search or a citation produce no results.

Cause. The servers’ build/ folders are not in the repository. Claude Code installs the plugin into its cache, but the servers cannot start until they are built there.

Fix. Build both servers inside the installed version folder, then restart Claude Code. For version 2.2.1, run these two commands in a terminal.

cd ~/.claude/plugins/cache/prima-scholar/prima-scholar/2.2.1/mcp-servers/prima-scholar-search-mcp && npm install && npm run build
cd ~/.claude/plugins/cache/prima-scholar/prima-scholar/2.2.1/mcp-servers/prima-scholar-library-mcp && npm install && npm run build

The Servers Stop Working After a Plugin Update

Symptom. Everything worked before you ran /plugin update, and now the servers are missing or failed.

Cause. An update installs the new version into a new version folder, which has no builds yet.

Fix. Run the two build commands above with the new version number in the path, then restart Claude Code.

The Installer Says the Workspace Is Not a Claude Code Workspace

Symptom. install.sh stops with ERROR: /path/to/workspace/.claude does not exist. Is this a Claude Code workspace?

Cause. The installer copies files into the workspace’s .claude/ folder and does not create it.

Fix. Check that you gave the right workspace path. If the path is right, create the .claude folder in the workspace and run the installer again.

The Installer Says PRIMA Scholar Is Cloned Inside the Workspace

Symptom. install.sh stops with ERROR: prima-scholar is cloned inside the workspace, or git warns about an embedded repository when you commit.

Cause. A clone inside the workspace becomes a git repository nested in your own, which git records as a link to another repository and not as files.

Fix. Move the clone outside the workspace, for example to ~/Developer/prima-scholar, and run the installer from there. If git has already committed the nested repository, the repository’s fix-nested-repo.md file gives the steps to remove it from git tracking. You can ask Claude Code to follow that file for you.

The Installer Says a Build Was Not Found

Symptom. The installer prints MCP: prima-scholar-search — build not found or the same line for prima-scholar-library, and skips that server.

Cause. The server has not been built in your clone. The installer copies the built server and its node_modules folder, and needs both.

Fix. Run npm install && npm run build in that server’s folder in your clone, then run the installer again.

The Installer Skips Registration

Symptom. The installer prints WARNING: ~/.claude.json not found — skipping MCP registration.

Cause. The installer registers the two servers in ~/.claude.json, and that file does not exist yet. The installer does not create it.

Fix. Add the two servers to Claude Code yourself, or use the plugin marketplace route, which does not need this file.

An Installer Update Still Runs the Old Servers

Symptom. You pulled a new version, rebuilt and re-ran the installer, but the servers behave as before.

Cause. When the server folders already exist in the workspace, the installer’s copy step places the new build and node_modules folders inside the old ones. The old server code stays where Claude Code runs it.

Fix. Delete .claude/mcp-servers/prima-scholar-search and .claude/mcp-servers/prima-scholar-library in the workspace before you re-run the installer. Your research library and keys are not stored there.

Your Changes to a Skill or Agent Disappeared

Symptom. After an update, a command, skill or agent you edited is back to its original wording.

Cause. The installer overwrites every command, skill and agent that PRIMA Scholar ships, by name, on every run.

Fix. Copy the file to a new name, such as my-researching-topics, and edit the copy. The installer never touches files with names it does not ship.

API Keys Disappeared After an Installer Update

Symptom. After an update with the installer, CORE results stop and missingApiKeys appears, or PubMed and Semantic Scholar run without your keys.

Cause. Installers before version 2.2.1 rebuilt each server’s settings when they re-registered it, and deleted every key except the contact emails and the library path.

Fix. Add the keys again to the env block of the prima-scholar-search entry in ~/.claude.json, then restart Claude Code. The 2.2.1 installer keeps the keys already there.

Keys Are Ignored in a Plugin Install

Symptom. You set a key, but CORE still reports a missing key or PubMed runs at the slower rate.

Cause. In a plugin install the servers read keys from the environment that Claude Code starts in. A key set after Claude Code started, or in a terminal that did not start it, never reaches them.

Fix. Add an export line for the key to your shell profile, open a new terminal and start Claude Code from it. API Keys and Configuration gives the details.

Commands Are Not Recognised

Symptom. Typing /scholar or /cite does nothing or reports an unknown command.

Cause. A plugin install puts the plugin name in front of every command.

Fix. Type /prima-scholar:scholar, /prima-scholar:cite, /prima-scholar:library or /prima-scholar:literature-watch.

Searching

CORE Is Missing From the Results

Symptom. The search returns results, but none from CORE, and the response carries a missingApiKeys line that starts core: API key not configured.

Cause. CORE needs a free API key, and the server skips it without one.

Fix. Get a key from CORE and set CORE_API_KEY, as API Keys and Configuration describes. The other nine databases work without it.

No Sources Available

Symptom. The search stops with No sources available. Missing API keys.

Cause. Every database you asked for needs a key you have not set. In practice this means you asked for CORE alone.

Fix. Set CORE_API_KEY, or add other databases to the search.

All Sources Failed

Symptom. The search stops with All sources failed, followed by one line per database.

Cause. No database answered. Each line gives that database’s reason, such as no network connection or the service being unavailable.

Fix. Check your internet connection, then run the search again. If one reason repeats, such as a status code from one database, leave that database out with sources.

One Database Reports an Error

Symptom. Results arrive, and an errors line reads, for example, Semantic Scholar search failed: 429 Too Many Requests.

Cause. That database refused or failed the request. A 429 means it is receiving too many requests, and a 5xx code means a problem on its side.

Fix. The results from the other databases are complete and usable. Wait a few minutes and search again, or leave that database out with sources.

A Date Is Rejected

Symptom. The search stops with a message such as published_after must be an ISO date: YYYY-MM-DD, YYYY-MM or YYYY.

Cause. The date window accepts only those three forms.

Fix. Give the date as 2026-09-01, 2026-09 or 2026.

Open Access Only Returns No PubMed Papers

Symptom. With open_access_only set to true, no PubMed results appear.

Cause. The PubMed connection marks every PubMed record as not open access, so the open access filter removes them all.

Fix. Search without open_access_only, or add Europe PMC, which reports open access status per paper. The Data Sources page describes each database.

Every Result Is Old

Symptom. You asked what is new on a topic, and the results are well-cited papers from years ago.

Cause. The default sort puts open access papers first and then orders by citation count, and new papers have few citations.

Fix. Ask for papers published after a date, sorted by date. Claude passes published_after with sort_by set to date.

A Paper Lookup Fails for a CORE or DBLP Identifier

Symptom. Looking up a paper by a CORE ID or a DBLP key returns an error or the wrong paper.

Cause. scholar_get_paper has no route to CORE or DBLP.

Fix. Look the paper up by its DOI.

Full Text Is Not Available

Symptom. A full-text request returns the source none and a message that the paper may be behind a paywall.

Cause. None of the four full-text routes holds the paper. Only CORE returns the text itself, and only with a key. Europe PMC, arXiv and bioRxiv or medRxiv return a download link.

Fix. Check your institution’s access or the publisher’s website. An arXiv link is built from the ID without checking that the paper exists, so a wrong ID gives a link that does not work.

bioRxiv and medRxiv Return Few Results

Symptom. A bioRxiv or medRxiv search finds little, even for a busy topic.

Cause. The connection downloads only the first page of the servers’ listing for the date range, then keeps the records whose title or abstract contains one of your query words.

Fix. Narrow the date range so the first page covers more of it, or add other databases to the search.

Your Research Library

The File Type Is Not Supported

Symptom. An import stops with Unsupported file type, followed by the extension and the list .pdf, .docx, .md, .txt.

Cause. The library imports only those four types. A .doc file from older versions of Word, a .markdown file and a .rtf file are all refused.

Fix. Save the file as one of the four supported types, or rename a .markdown file to .md, and import it again.

The File Cannot Be Found

Symptom. An import stops with a message containing ENOENT: no such file or directory.

Cause. The path is wrong or not absolute, because the library does not expand ~ to your home folder.

Fix. Give the full path, starting from /, for example /Users/you/Documents/paper.pdf.

A PDF Fails to Import or Imports Almost No Text

Symptom. The import stops with Failed to parse PDF, or it succeeds with a very low extractedLength and the record never appears in searches.

Cause. The PDF is damaged or password protected, or it holds images of pages with no text layer. The library reads text only and has no character recognition.

Fix. Open the PDF in a reader to check it. For a scanned PDF, create a text version with a character recognition tool first, then import that.

A Library Search Fails With a Syntax Error

Symptom. A library search stops with a message such as no such column: efficacy or fts5: syntax error near.

Cause. The library search has its own query language. A hyphen, colon, apostrophe or question mark in a plain word is read as part of that language.

Fix. Put the word or phrase in double quotes, as in "self-efficacy", and leave out question marks.

Creating a Collection Fails

Symptom. Creating a collection stops with UNIQUE constraint failed: collections.name.

Cause. A collection with that exact name already exists.

Fix. List your collections and use the existing one, or choose another name.

A Collection Is Not Found

Symptom. Adding a record to a collection stops with Collection "name" not found.

Cause. No collection has exactly that name. Names must match exactly, and the tool does not create a missing collection.

Fix. List your collections to check the spelling, or create the collection first.

Tagging or Filing a Record Fails

Symptom. Adding a tag or adding a record to a collection stops with FOREIGN KEY constraint failed.

Cause. No record has the document ID you gave.

Fix. Search or list the library to find the right ID, then try again.

A Tag Filter Finds Nothing

Symptom. Listing records by a tag returns nothing, although you know you tagged some.

Cause. Tags are case-sensitive, so Burnout and burnout are separate tags.

Fix. Check the exact tag on one of the records, then filter with that spelling.

The Same Paper Appears Twice

Symptom. The library holds two records for one paper.

Cause. Neither import tool checks for a record with the same DOI.

Fix. Search the library before you import, and delete the extra record.

Your Library Looks Empty

Symptom. Records you imported earlier no longer appear.

Cause. The library server opened a different database file. It uses RESEARCH_LIBRARY_PATH when that is set and ~/.research-library/library.db when it is not. Before version 2.2.1, two further cases occurred. An empty path opened a temporary database that was discarded when the server stopped. In a plugin install, an unexported path created a file named ${RESEARCH_LIBRARY_PATH} in the folder where Claude Code started.

Fix. Check the value of RESEARCH_LIBRARY_PATH where your installation reads it, and set it to the file that holds your records. If you used a version before 2.2.1, look for a file named ${RESEARCH_LIBRARY_PATH} in the folders where you start Claude Code, because it may hold records imported then.

Literature Watch

The Watch Asks to Create a Settings File

Symptom. /literature-watch stops and offers to create a settings file.

Cause. The workspace has no .claude/literature-watch/config.md yet.

Fix. Accept and answer the two questions, and read the Literature Watch page for every setting.

The Same Papers Return Every Run

Symptom. Each digest lists papers you saw last time.

Cause. The state file was not updated, so the watch does not know which DOIs it has shown you. The update uses jq, so it fails when jq is not installed. A dry run also leaves the state file unchanged.

Fix. Install jq, then check that lastRun and seenDois in .claude/literature-watch/state.json changed after the last full run. Check that the JSON file beside the digest lists DOIs.

The Scan Comes Back Empty

Symptom. The digest finds no papers, or very few.

Cause. Databases add new papers with a delay of days to weeks, so a recent start date can catch little.

Fix. Widen the window with since, for example /literature-watch since 2026-09-01, or accept a quiet week.

CrossRef Results Bunch on the Last Day

Symptom. A group that searches CrossRef returns papers from only the last day or so of the window.

Cause. Sorted by date, CrossRef returns the newest records that match any query word. On a broad query those cover less than a day.

Fix. Set sort_by: relevance on groups that search CrossRef, and the date window still limits the results.

The Venue Filter Finds Almost Nothing

Symptom. A group or the venue sweep with venues returns few or no papers.

Cause. The venue filter runs after the search, so it can only keep records the search already fetched. A venue name that does not match the database’s journal name keeps nothing.

Fix. Put the publisher or journal name in the query, set sort_by: relevance and raise the group’s max_results. Use short, distinctive parts of journal names, such as Applied Psychology, not the full title.

A Tool Reports That published_after Is Not Found

Symptom. The scan fails with a message that the tool or the published_after parameter is not found.

Cause. The search server is older than version 2.1.0, which added date windows.

Fix. Rebuild the search server from the current version and restart Claude Code.

Still Stuck

If your problem is not listed here, see Getting Help.