# Troubleshooting

> The messages you may see, and how to fix each one.

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.

## "Server off. Start the Content Server in Calibre (Connect/share → Start Content server) to index books."

**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](collections.md).

## 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](collections.md).

## 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](https://github.com/insurgently/topic-map/blob/HEAD/SUPPORT.md).