Troubleshooting¶

Human-oriented recovery for common failure modes. Agents already carry short recovery tables in each SKILL.md; this page is the longer catalog with UI and environment checks.

When in doubt: re-run sr-initialize. It re-probes and only does what is still missing.

Sections follow the user guide order. Each symptom is its own heading so you can deep-link it.

Quickstart¶

Skills missing after marketplace install¶

Reload the window; confirm the plugin is enabled in the harness plugin UI.

Cursor hooks / auto-dashboard never fire¶

Enable Include third-party Plugins, Skills, and other configs (see the Quickstart screenshot). Then reload.

“Add plugins from folder” rejects this repo¶

Expected — stockroom is a plugin, not a marketplace. Install via txrk9-agent-plugins.

Local checkout skills do not load¶

Contributor localdev wires a Cursor skills mirror after you uninstall the marketplace plugin — see Preparation. Confirm make localdev-status shows the skills mirror, reload the window, and use HARNESS=cursor make localdev (Claude uses claude --plugin-dir instead of a skills mirror). Marketplace sessionStart hooks are gone after uninstall; the dashboard remains reachable via stockroom dashboard / make local-dashboard.

Installed layout¶

`stockroom: command not found`¶

Prefer, in order:

sr-initialize when you can spend an agent turn — it re-probes and only does what is still missing (Quickstart).
New harness session — session-start hooks run shim rectify, which can create a missing on-path shim, rebake an owned one after a plugin path move, or replace one whose engine directory is gone (such as a deleted dev checkout).
Last resort: bind the shim yourself — when the marketplace plugin is already installed and you cannot spend an agent turn.

What lands on disk: Installed layout.

Last resort: bind the shim yourself¶

The shim is baked to one engine directory (…/skills/sr-search). Bind the install that is already on disk — not a random git clone. The same recipe lives in your installed plugin under skills/sr-initialize/SKILL.md, btw.

Find the engine dir (pick the marketplace/plugin tree you actually run — not a contributor checkout unless that is intentional):
```
find ~/.cursor/plugins ~/.claude/plugins -type d -path '*/skills/sr-search' 2>/dev/null
```
If a broken on-path shim still exists, its header names the baked directory: grep '^# STOCKROOM_APP_DIR=' "$(command -v stockroom)".

Set APP_DIR to that absolute path and choose the owner for this harness (cursor or claude):

APP_DIR=/absolute/path/to/skills/sr-search
OWNER=cursor   # or: claude

PYTHONPATH="$APP_DIR/src" uv run --project "$APP_DIR" --no-sync --no-config \
python -m stockroom shim install --owner "$OWNER" --app-dir "$APP_DIR"

Confirm:

command -v stockroom
stockroom --version

If the installer warns that ~/.local/bin is not on PATH, add it and retry the check.

Ownership: if install refuses because another owner's shim is alive, read the refusal line. Replacing a live foreign shim needs explicit --takeover --force; a dead one needs only --takeover, and the next harness session replaces a dead shim on its own. Prefer sr-initialize, which asks before replacing a working shim.

Shim refuses with a one-line remedy¶

Follow the remedy printed on stderr. Often that is: open a new session so shim rectify can heal, or re-run sr-initialize. If you cannot use an agent turn and the remedy is effectively “rebind the launcher,” use the last-resort bind under stockroom: command not found.

Engine env cannot import locked deps¶

Let session-start heal run (shim rectify includes ensure-env), run stockroom shim ensure-env yourself, or re-run sr-initialize.

Ingest¶

Move the warehouse file aside¶

stockroom migrate prints one line and exits 1. The line names the warehouse file and gives an mv command.

A first run created the warehouse file and did not finish. The warehouse file holds no history. The warehouse file is not damaged. Stockroom cannot run the next migration on the warehouse file. The next migration needs software that Stockroom does not load, so Stockroom stops.

Stockroom does not delete the warehouse file. Stockroom does not create a new warehouse on the same path while the warehouse file is there. Each later open fails in the same way until you move the warehouse file. The mv command in the error names this warehouse file. After the move, the same command can create a new warehouse. The old warehouse file stays on disk under a name that ends in .old.

stockroom ingest raises the same error. stockroom ingest does not print one line. The error text still gives the mv command.

Copy the mv command from the error text. Stop before , then run.
Run the mv command. The mv command moves the warehouse file to a name that ends in .old.
Run the same command again.

Empty or sparse results after first install¶

Confirm the first ingest + embed finished (sr-initialize). Wait for the nightly schedule, or run ingest/embed yourself — Load the Warehouse · CLI.

Weak semantic results for recent work¶

Silent staleness is possible: ingest may have new messages that are not embedded yet. Catch up with stockroom ingest then stockroom embed before concluding the content is absent — Load the Warehouse.

Nightly schedule installed but nothing updates¶

Check stockroom schedule status. If the cron daemon is not running, the entry is written but will not fire (WSL: sudo service cron start, or enable systemd). If it says up-to-date: no, the entry is from an older Stockroom or for another stockroom home, and the job may be filling a different warehouse: compare entry home: with the home in log:, then re-install with stockroom schedule install --time HH:MM. See Scheduling.

Search¶

SQL errors on write-looking statements¶

Read surfaces open the warehouse read-only by construction — use ingest/embed for writes (Search · CLI).

Truncated-looking cells in output¶

Truncation is read-time only; use a higher --detail (or refetch a targeted row). Full content remains in the warehouse (CLI).

Semantic search returns nothing useful¶

Confirm the warehouse has embeddings (ingest + embed), then decide structured vs meaning-based — Search. If the error cites torch / the environment, see Torch.

Dashboard¶

Dashboard UI will not load¶

Something is answering on the dashboard port, but you are not getting the real UI — blank page, odd HTML, or the short in-browser recovery page that says the dashboard could not load this page. There is no single root cause; the steps below are common things worth trying, not a diagnosis of your machine.

Things that sometimes contribute¶

A stale dashboard process left over after a plugin update, still bound to the port but no longer able to serve current static assets.
An on-path stockroom shim that is missing, or still baked to an old plugin path. Harness hooks are one way that path gets refreshed (they can see CURSOR_PLUGIN_ROOT / CLAUDE_PLUGIN_ROOT). If stockroom itself is missing or refuses, terminal commands that start with stockroom … may not be able to find the correct install on their own.
Less often for this symptom: a broken engine env (locked deps missing from the engine .venv) that blocks starting a new listener. The dashboard does not use Torch, so Torch issues are usually a different problem — Torch · Engine env cannot import locked deps.

Things to try¶

From the harness. Open a new chat and run /sr-dashboard (Claude Code: /stockroom:sr-dashboard), then reload http://127.0.0.1:58008/. On Cursor, submitting a short prompt can refresh the on-path shim via before-submit suspenders, but that path does not validate the engine env or launch/replace the dashboard — still run /sr-dashboard (or rely on session-start) before expecting the UI to recover.
Cursor hooks. If auto-heal never seems to run, check the third-party plugins setting — Quickstart.
If stockroom is missing or refuses. In a chat, try /sr-initialize (Claude Code: /stockroom:sr-initialize) and ask it to restore the on-path shim and get the dashboard serving. That skill can see the plugin tree even when the shim cannot.
If stockroom --version already works but the page is still wrong, stockroom dashboard --replace can replace a stale listener. If the shim is not healthy yet, --replace often does nothing useful.
Without an agent turn. Last-resort manual bind — last-resort bind under stockroom: command not found.

The in-browser recovery page links here for the longer walkthrough. API clients still see JSON 404 for unknown /api/* routes.

Port 58008 already in use¶

When stockroom --version works but the UI looks stale, try stockroom dashboard --replace (or stop the old stockroom.dashboard process once, then /sr-dashboard) — Dashboard. If you are not sure the shim is healthy, the broader checklist above may be a better starting point.

Auto-start missing on Cursor¶

Third-party plugins setting (Quickstart above). If that is already on and nothing seems to auto-heal, the Dashboard UI will not load checklist is the next place to look.

Warehouse¶

Session start runs a check on the warehouse file. The check runs in the background and does not ask first.

If the warehouse uses the older storage format and the check can copy it safely, the check makes a trial copy in the new format, verifies it, and deletes it. At least one day later, if the warehouse can still be copied safely, a session start makes a new verified copy and puts it in place of warehouse.duckdb. The check keeps the original file in the same directory, under the name warehouse.issue147-swap.duckdb. That file stays for 14 days after the new warehouse is the one in use. A later session start can remove it after those 14 days. If a step fails, the check keeps the original in place.

The check does not copy when it is not safe. For example, free disk can be low, a database write can be incomplete, or an ingest can still need to bring the warehouse to the current schema. Then the check does nothing, and a later session start begins again with a trial copy. If a copy does not pass verification, the check stops and keeps the original in place. A warehouse that already uses the new format is recorded as already-new. The check does not copy it or replace it.

Put the original warehouse back¶

When this applies. The check replaced warehouse.duckdb, and you want the original back. Run stockroom doctor probe. Two values tell you where you are: the backup line, and the first word after check:.

warehouse:         /home/you/.local/share/stockroom/warehouse.duckdb
backup:            /home/you/.local/share/stockroom/warehouse.issue147-swap.duckdb
check:             swapped original_bytes=… path=…

If the backup line says absent, there is no original file to put back.

The problem. The replacement takes more than one step. While the check word is running or linked, the check can still replace warehouse.duckdb, so a rename that you make can be undone. Also, a writer (ingest, embed, or the nightly job) that finds no warehouse.duckdb makes a new, empty one.

The solution. Rename the files only when the check word is swapped. That word means the replacement is complete. The check leaves warehouse.duckdb in place. The check removes the backup 14 days after the new warehouse is the one in use. Put the original back before then. A session that starts after those 14 days can remove the backup in the background. A session during the 14 days does not remove the backup. If the word is running, wait for the check to end. If it is linked, one new session lets the check complete the replacement. For any other word, do not rename a file. Keep check.json after the restore. If you delete it, a later session start can copy and replace the restored warehouse again.

To put the original back:

Run stockroom doctor probe. If the backup line says absent, stop. There is nothing to put back.
If the warehouse line says busy, or the check word is running, wait. A copy of a large warehouse can take hours. Then go to step 1.
If the check word is linked, start one new session in Cursor or Claude Code. Wait ten minutes, then run stockroom doctor probe again. If the warehouse line says busy, wait and run it again. If the word is still linked, stop and see Still stuck. Do not start another session.
If the check word is not swapped, stop. Do not rename a file. See Still stuck.
Make sure that no writer runs during steps 6 to 9. Do not run stockroom ingest, stockroom embed, or the nightly job.
Run stockroom doctor probe again. If the warehouse line says busy, wait and run it again. Continue when the warehouse line shows a path.
Go to the directory that contains the file on the backup line.
Rename warehouse.duckdb to warehouse.replaced.duckdb. Do not use warehouse.copy.duckdb, because the check deletes a file with that name. If warehouse.duckdb.wal exists, rename it to warehouse.replaced.duckdb.wal.
Rename warehouse.issue147-swap.duckdb to warehouse.duckdb.
Run stockroom doctor probe. The backup line says absent, and the check word is still swapped.

Still stuck¶

Ask the agent with /sr-search (or Claude /stockroom:sr-search) and describe the error text — Skill index.
Torch / embeddings / heal soft-fails: Torch.
Contributors debugging from a checkout: Preparation · Iteration.