Source: https://velofy.co/trove/troubleshooting/

[Trove](https://velofy.co/trove/) / Guides

# Troubleshooting and limits

Fixes for common Trove problems: missing indexes, refused entries, stale skills, provider and ship errors, plus the known limits of the current code.

Each entry below names the symptom you see, why it happens, and what to do.

## First principles

Most Trove problems come from one of three places: which folder a command treats as the repository, which files exist yet (an index, a trove, a cache), and a guard doing its job (a refused secret, a fail-closed ship). Check those three before anything else. The messages quoted below are printed by the current code.

## The index

### `No index found. Run: trove index`, but you already indexed

`index`, `status` and `query` use the current directory as the repository unless you pass `--repo`. Run from a subdirectory, they look for `.trove/` there, and also leave an empty `.trove/` behind. Run them from the repository root, or pass `--repo /path/to/repo`, and delete the stray `.trove/`. `trove ask` and `trove remember` search upward for the root, so they do not have this problem.

### `Error: No such file or directory (os error 2)`

`trove index` was given a `--repo` path that does not exist. The other subcommands create the path instead, so a mistyped `--repo` with `status` prints `No index found` and leaves an empty `.trove/` there.

### Every run reports all files as stale

`(134 stale rebuilt)` on a second run is expected in the current code: the incremental check compares two different hashes that never match, so every run is a full rebuild. See [Indexing a repository](https://velofy.co/trove/indexing/).

### Deleted files still appear in `.trove/`

Re-indexing drops deleted files from `symbols.json` and the counts, but not their JavaScript Object Notation (JSON) files in `.trove/modules/` and `.trove/symbols/`. Delete `.trove/` and index again.

### Query results include `.claude/` files

Hidden files are indexed unless Git ignores them, so the project trove and its rendered skills show up as modules. This is expected. They are small and rank low for code questions.

## Asking

### No symbols or modules in `trove ask`

The footer says there is no engine index. Run `trove index` in the repository.

### The first `trove ask` is slow

Without `--no-tools`, the first run builds the installed tool catalog. Later runs reuse the cache and rescan only changed folders. Pass `--no-tools` when you only want troves, docs and code.

### Good sources are missing

Ranking is lexical. Use the words and identifiers the code uses, raise `--limit` (default 12) or `--budget` (default 1,500) when the footer shows many more matches than hits, and check the hit caps: at most 6 per kind and 3 tools.

### `retrieval only (...)` in the footer

A provider was requested but the answer step failed, so `ask` printed the sources only. The message in brackets says why:

*   `set ANTHROPIC_API_KEY (or ANTHROPIC_AUTH_TOKEN) to use --provider anthropic`: export one of them.
*   `run curl (is it installed?)`: install `curl`; the Anthropic and Ollama providers call it.
*   `ollama: ...` or a `curl:` error: start Ollama, or set `OLLAMA_HOST`.
*   `` `claude -p` failed: ... ``: the `cmd` provider’s command failed; set `TROVE_LLM_CMD` to a command that reads standard input.
*   `redaction refused: ...`: a secret-shaped string survived redaction, so nothing was sent. Find the entry or doc it came from and remove the secret.

## Writing memory

### `no trove found at ... create one first`

`trove remember` needs an existing trove. Run `/trove:init` in Claude Code, or `trove.sh init`.

### `entry '<slug>' already exists ...; rerun with --update to replace it`

The title produces a slug that is already taken. Pass `--update` to replace the entry (its `created` date is kept), or choose another title.

### `unknown type '<type>'; expected one of ...`

`--type` takes exactly `convention`, `decision`, `gotcha`, `preference`, `reference`, `project`, `snippet` or `context`.

### `refusing: possible secret at line <n> (...)`

The entry looks like it contains a credential, so nothing was written. Rewrite it without the value; keep what was non-obvious, such as where the real value lives.

### `--section needs a sectioned project trove`

`--section` only works with a project trove. Without one, `trove remember` writes into the flat personal trove.

### `provide --body or pipe the entry body on stdin`

Give the body with `--body "..."` or pipe it in.

### A rendered skill does not show a new entry

`trove remember` writes the entry and the index line but does not re-render the skill. Run `trove.sh render <section>`, or start a new session: the SessionStart hook re-renders any section that changed. If `.claude/skills/` did not exist when the session started, run `/reload-skills`.

## The plugin

### `/trove:query` fails outside the Trove repository

The `query` skill calls `cargo run -p trove-cli`, which only resolves inside a Trove checkout. Install the binary with `cargo install --path crates/trove-cli` and run `trove query`, or ask Claude to use the binary.

### `No engine index at ... Run the indexer first (/trove:index).`

`trove.sh context` needs `.trove/manifest.json`. Run `trove index` first.

### `trove.sh context needs jq or python3 to read .trove/.`

Install either one.

### Skills from a manual install cannot find `trove.sh`

The skills call `"${CLAUDE_PLUGIN_ROOT}/scripts/trove.sh"`, a variable Claude Code sets only for plugins. Install through the marketplace, or tell Claude to use `plugins/trove/scripts/trove.sh` from your clone.

### `Permission denied (publickey)` when adding the marketplace

You have no Secure Shell (SSH) key on GitHub. Use `/plugin marketplace add https://github.com/anishfyi/trove.git`.

### The marketplace is listed as `anishfyi-trove`

It was renamed to `velofy-trove` on 2026-09-12. Install with `/plugin install trove@velofy-trove`.

## Handoff docs

### `... is not empty and was not written by trove-ship; pass --force or pick another --out`

Ship only replaces folders it created. Choose an empty folder, or pass `--force` once you are sure nothing there matters.

### `refusing to write: <n> high-confidence secret(s) survived redaction`

Exit code 2, nothing written. The lines after it name the output document, line and detector. Find the source, remove the secret and rotate it, or exclude the source file in `.troveignore`. See [Handoff docs with trove ship](https://velofy.co/trove/ship/).

### `agent review of <file> failed; nothing was written`

The agent command failed or timed out. Check that `claude`, `codex` or `pi` runs non-interactively, or raise `--agent-timeout`.

### Conventions are missing from `conventions.md`

Ship includes entries of type `preference`, or entries tagged `convention`. Add the tag to `convention` entries.

## The tool catalog

### `trove tools ls` describes `ls`

A tool name wins over a subcommand word it does not match. To list the catalog, run `trove tools` or `trove tools list`.

### A tool has no summary

It has no man page. Run `trove tools refresh --probe`, or `trove tools <name>` for that one tool.

## Exit codes

*   `0`: success.
*   `1`: a runtime error, printed as `Error: <message>` (or `trove ship: <message>`).
*   `2`: an argument error reported with a usage line, or a fail-closed `trove ship`.

## Limits by design

*   **No embeddings.** Retrieval is lexical and misses synonyms. In the repository’s evaluation, `trove ask` finds the expected item in its top five for every exact-term and symbol query and for half of the synonym queries.
*   **No model in indexing.** Summaries list names and flags; they do not explain intent.
*   **No prebuilt binaries.** Build from source with Cargo.
*   **Platforms.** Continuous integration (CI) builds and tests on Ubuntu and macOS. The tool catalog knows the macOS and Linux install locations.
*   **No call graph.** The dependency graph holds import edges only.