Troubleshooting and limits

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.

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.

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.