Troubleshooting

Common problems and how to fix them.

"Couldn't load data/papers.json"

Browsers block a page opened straight from disk (file://…) from loading other files. Serve the app instead, from the annotation_explorer folder:

python -m http.server 8765 --directory web

and open http://localhost:8765. If it still fails, the data file may not exist yet: run python pipeline/build_index.py first.

"Address already in use" when starting the server

Another server is already using port 8765, possibly an earlier copy of the app; try opening http://localhost:8765. Otherwise use another port, e.g. python -m http.server 8766 --directory web.

A new or edited paper doesn't show up

Run python pipeline/build_index.py; the app only reads the built data file.
Reload the page. If the browser still shows old data, do a hard reload (Ctrl+Shift+R, or Cmd+Shift+R on a Mac).
Check the build output for Skipped invalid ingestion records: a record with a mistake is left out until it's fixed, and the message says what's wrong.
The record's file name must be the paper's id (<id>.json) and its id field must match. See adding papers.

The same tool appears twice in the usage charts

Two spellings aren't linked in the vocabulary yet. Add the second spelling as an alias in vocab/vocabulary.json and rebuild. Names marked * aren't in the vocabulary at all (vocabulary).

The layout looks wrong or a panel is too small

Double-click a border between sections to reset it.
To reset everything, clear the site's stored data in your browser for localhost.
Below about 980px wide the sections stack vertically; this is intentional.

A paper says "Not ingested yet"

The agent hasn't read it, so only its ranking and metadata are available. Its panel shows the commands to ingest it (adding papers).

Many workflow steps say "Unknown"

The agent could only read the abstract (the source line at the bottom of the summary says so). Those steps are left out of the cross-paper counts. Re-ingest the paper if a full text becomes available.

A help link goes to the wrong place

Run python pipeline/check_help.py; it lists broken help links and missing sections (maintaining the help).