Troubleshooting · Topic Map

Start at Settings → Topic Map → Setup. Connections says what Topic Map can reach, in plain words.

"Topic Map needs Model Hub for every model call. Install and enable Model Hub from Community plugins."#

Why: Model Hub is missing or turned off. Fix: install and enable Model Hub, then add a provider in its settings.

"Topic Map needs Model Hub API …; the installed Model Hub offers …. Update Model Hub."#

Why: Model Hub is older than Topic Map needs. Fix: update Model Hub in Settings → Community plugins.

"Not installed, so book collections are unavailable. Notes and Bases work without it."#

Why: Library Hub isn't installed. Fix: nothing, unless you want collections of books. Then install Library Hub.

Why: Books come through Calibre's Content Server, and it isn't running. Fix: start it in Calibre, then select the check button under Connections.

"Content Server on, read-only: books with only an AZW3 or MOBI can't be converted…"#

Why: Calibre's server answers but doesn't allow changes, and converting a book adds an EPUB to it. An index runs, but leaves those books out and names them in its report. Fix: in Calibre, Preferences → Sharing over the net → Advanced → Allow un-authenticated local connections to make changes, Apply, then stop and start the server. The row under Connections says the same, and Library Hub's guide has the full table of settings Calibre needs.

"Opening a book at the passage needs Library Hub 0.5 API or later. Update Library Hub."#

Why: Open in book asks Library Hub to open the book at the passage, which it can do from version 0.5. Everything else works with the older one. Fix: update Library Hub. Until then, the passage opens in Topic Map instead.

"The passage wasn’t found in the book, so it opened at its start."#

Why: the reader couldn't find the card's quote or the passage's chapter in the book: the book file may have changed in Calibre since the collection was indexed, or the quote may cross a page break in a PDF. Fix: search the book in the reader for a few words from the passage, or index the collection again.

"Groups are out of date"#

Why: the cards, their vectors or your Not the same and Join with… answers changed since the repeated terms were last grouped, so the groups can’t be trusted. The Groups tab says so, and search and Find topics show every card on its own until you group again. Fix: select Group again on the panel’s Groups tab. It costs nothing. An index made before groups existed offers Group cards instead.

"Repeated terms aren’t grouped"#

Why: the groups file in the collection’s folder can’t be read: it isn’t valid JSON, or it isn’t a groups file. Search and Find topics still answer, with every card on its own, and the message names the problem. Fix: select Group again on the panel’s Groups tab, which writes the file again. It costs nothing.

"Cards weren’t grouped again"#

Why: the file that keeps your Not the same and Join with… answers can’t be read, so the index run left the groups as they were. The run still finished, and the message says what is wrong with the file. Until it is fixed, the groups count as out of date. Fix: undo the corrections from the Runs tab, or fix or remove the answers file in the collection’s folder under the plugin’s corpora, then select Group again.

"No collection notes in …"#

Why: the collections folder has no collection note. Fix: make one with New collection… on the Collections tab. See Make a collection.

A collection note is refused, naming a property#

Why: the note's properties can't be read: reader or source is missing or misspelled, or the properties aren't valid YAML. Fix: the message names the property. Compare the note with the example in Make a collection.

A job "has made no progress for five minutes"#

Why: a model call is slow or stuck. Fix: wait, or cancel it from the panel’s Runs tab. A later run picks up where it stopped.

A run stopped at a limit#

Why: it reached the spend limit you set, or one of Model Hub's: a tier's per-call limit or monthly budget. Fix: raise the limit and run it again. What was already read is kept. For Model Hub's limits, see its Tiers tab.

A draft wrote nothing#

Why: the model's reply was cut off at the length limit, or wasn't a draft Topic Map could read. Fix: the message says which, and where the reply is kept. Try again with fewer seeds, or move topic-map.write to a tier with a model that allows longer replies.

"No Topic Map run to undo."#

Why: there are no runs, or the run is older than the last five of its kind. Fix: none. Older runs can't be undone.

Report a problem#

Open Report a problem… from the panel's ⋯ menu, or from Commands… under Setup. Describe what happened, then press Collect. You see the whole report before anything leaves your computer, with a checkbox for each section, and then choose to open a GitHub issue, copy it, save it as a file or email it. Topic Map sends nothing itself.

Its section holds counts and states only: how many collections, passages and cards are indexed and how large the index is, the state and length of recent jobs and runs (and, for a job that failed, a short code for why, such as model-error, budget-stopped or vector-worker, never its message), how much memory the window and the vector worker use, whether memory was let go under pressure, and the versions of Topic Map, Model Hub and Library Hub. It never holds a note's name or text, a collection's name or a path, and the report also removes them from the description you write. Topic Map keeps no keys of its own (your model keys live in Model Hub), so none can appear.

Questions#

My new lens doesn't show#

Reload the skills in Model Hub, then open the Lenses tab. If it shows with a problem, run Check my lenses.

How do I find a job in my traces?#

Turn on traces in Model Hub's settings. Each Topic Map job is one run span, named for the job and its collection (run plugin:topic-map: index Garden notes; the attribute hub.run.label holds index Garden notes), with the job's model calls under it (roles topic-map.extract, topic-map.name and so on). A search is a single call of its own, outside any run. A failed or refused call is marked as an error.

Does it work on mobile?#

No. Topic Map is desktop only.

Will uninstalling delete my work?#

It deletes the indexes, which live in the plugin's folder. Your notes stay. Copy .obsidian/plugins/topic-map/corpora out first to keep the indexes.

Still stuck? See Getting help.