Troubleshooting
What usually goes wrong.
The common errors, grouped by phase. If none of these match, open an issue with the backend terminal output, the browser console, and the provenance JSON for the operation that failed.
01 · Setup
Install and run.
./setup.sh fails on sentence-transformers.
Python is older than 3.11. Check with python3 --version. On macOS, brew install python@3.11, then run python3.11 ./setup.sh.
npm install fails on three or plotly.
Node is older than 18. Check with node --version. Upgrade, or nvm install 20.
Backend starts but the frontend can't reach it.
The frontend proxies /api/backend/* to http://localhost:8000. If uvicorn is on a different port, create .env.local at the repository root with THEORYSCOPE_BACKEND_URL=http://localhost:<port> and restart npm run dev.
02 · Zotero
Credentials and connection.
Theoryscope connects but comes back with zero items.
The key does not have library access. Go to zotero.org/settings/keys, click Edit on the key, tick Allow library access and save. For a group library the group itself needs read permission on the key. Full walkthrough: the Zotero API key page.
"Invalid library" or a 404 response.
The library ID is wrong, or the library type does not match. The library ID is a plain integer, not your username. For a group library the ID is the group's number in the URL at zotero.org/groups/<number>/<name>, and the library type must be group.
I see items on zotero.org but Theoryscope only loads a handful.
Theoryscope paginates through the Zotero API in blocks of 100. If a request fails mid-stream the panel shows a partial corpus. Click Reconnect to re-fetch.
I pasted the key but Theoryscope keeps asking for it.
Credentials live in localStorage for localhost:3000. Clearing site data for that origin resets them. The key is never written to the backend cache or logs.
03 · Embedding and models
Model downloads and memory.
First run is slow.
The default embedding model (all-MiniLM-L6-v2, around 90 MB) downloads on first use. Subsequent runs are offline. The Embedding Dependence Probe downloads all-mpnet-base-v2 (around 420 MB) and BAAI/bge-small-en-v1.5 (around 130 MB) when first selected. The Corpus-vs-Model Probe downloads a small generative model (SmolLM2-135M at around 270 MB, SmolLM2-360M at around 720 MB, GPT-2 at around 500 MB).
HuggingFace rate limit on first download.
Unauthenticated downloads are rate-limited. Create a free token at huggingface.co/settings/tokens and export HF_TOKEN=<your token> before starting the backend. Theoryscope itself does not need a HuggingFace token; this only raises the download rate limit.
Out of memory on a large corpus.
Embedding runs in batches but the final matrix is held in memory. A corpus of 5,000 abstracts under MiniLM (384-dim) is around 15 MB. The Corpus-vs-Model Probe is the heaviest operation; smaller models (SmolLM2-135M) fit comfortably on 8 GB RAM machines, the larger ones on 16 GB.
04 · Operations
Visualisation and exports.
Corpus Map renders but points stack at the origin.
The embedding call failed and returned zero vectors. Check the backend terminal: usually a Zotero fetch failure (empty titles and abstracts), or the embedding model failed to download. The provenance panel will show the corpus hash as all-zeros, which is the giveaway.
Eigendirections look like garbage on a small corpus.
PCA on fewer than around twenty documents is unstable. Run the Forgetting Curve: if the standard deviation on PC1 is above 0.3 the eigenbasis is noise. Add documents, or use a larger embedding model.
Export button downloads an empty file.
The operation has not completed. Wait for the status indicator in the deep-dive panel to clear before exporting.
05 · Still stuck
Open an issue.
File at github.com/vector-lab-tools/theoryscope/issues with:
- The backend terminal output around the error.
- The browser console (Cmd/Ctrl + Alt + I → Console tab).
- The provenance JSON for the operation that failed, from its Export button.
Do not paste your Zotero API key into an issue. If a redacted log is needed, replace the key with <redacted> before attaching it.