troubleshooting.md

# Troubleshooting

Start with the same data directory used to register the book. Keep ordinary diagnostics machine readable; do not paste API keys or full service response bodies into reports.

```powershell
book-agent list --data-dir ".\BookAgentData" --json
book-agent doctor "<registered-book-id>" --data-dir ".\BookAgentData" --json
book-agent status "<registered-book-id>" --data-dir ".\BookAgentData" --json
```

## Package/import diagnostics

| Diagnostic | Action |
| --- | --- |
| `package_root_missing`, `required_file_missing`, `declared_file_missing` | Select the actual package root or obtain a complete package. A chunk directory is not required. |
| `multiple_packages` | Select a specific reported package directory rather than importing a multi-book parent ambiguously. |
| `invalid_manifest`, `unknown_archive_schema` | Obtain a valid supported manifest or implement an explicit format adapter. Preserve the original manifest for comparison. |
| `checksum_mismatch`, `file_size_mismatch`, `source_version_mismatch` | Obtain matching original files/manifests. Do not edit expected hashes to make a damaged input pass. |
| `unsafe_path`, `unsafe_link`, duplicate/case-colliding entries | Reject the archive. Request a clean archive from its source. |
| Archive count/byte/compression limits | Confirm the input before deliberately selecting appropriate limits through the API; do not bypass path/link validation. |
| `archive_dependency_missing` | Install the approved archive dependency from the runtime distribution/wheelhouse. |
| `archive_path_too_long` | Select a shorter data directory on the chosen workspace drive; preserve the input archive. |
| `import_busy` | Wait for the existing import. Inspect stale import state before removing any lock manually. |
| `managed_import_changed` | Reinspect the changed managed copy. Do not overwrite the source archive or silently reuse its old receipt. |

An existing database with unsupported schema/vector encoding requires an adapter based on its actual schema/manifest. Unknown binary vectors must not be guessed as float32. Incomplete WAL/journal state requires a complete publisher snapshot; do not checkpoint or repair the original in place. SQLite extensions are never loaded merely because input data names them.

## Query runtime and fallback

The default `--vector-search none` uses lightweight lexical/FTS retrieval. It needs no query weights or API key, and original Skill/PDF/EPUB source/image tools remain available. Enable `offline` only with the original compatible local query checkpoint and optional Python `local-query` dependencies; enable `online` only with authorized access to the inherited reviewed endpoint and the user's own credential reference.

`lexical_fallback` means evidence came from text search after compatible semantic query generation was unavailable. It is useful retrieval with a declared limitation. Preserve the actual tool status for deliberately disabled vectors and unavailable optional vectors; do not relabel text scores as semantic scores. `--strict` returns an unresolved vector-query error when the selected route requires a query encoder.

| Diagnostic | Action |
| --- | --- |
| `metadata_conflict`, `model_space_conflict` | Compare archive, vector manifest, README, SQLite metadata and the reviewed query implementation. Supply a supported paired-space contract. Equal vector dimensions do not establish compatibility. |
| `query_runtime_unverified` | Supply the original index's complete query contract; continue with explicitly labeled lexical search while it is incomplete. |
| `query_credentials_missing`, `query_credential_reference_missing` | Set the required environment variable in the runtime/host process and configure its name with `--query-auth-env`. Do not put the value in a book manifest or host config. |
| `remote_query_disabled`, `query_endpoint_not_allowed` | Authorize current-question transfer only to the inherited reviewed endpoint, then set the explicit endpoint allowlist. |
| `query_local_model_missing`, `query_local_model_unverified` | Validate the delivered original compatible local query directory with `install-query-model --model-dir`, then bind it with `configure --query-model-path`; verify its identity/revision and portable file-hash receipt. A replacement model with matching dimensions is insufficient. |
| `query_dependency_missing` | Install the reviewed optional query dependency offline when possible. Do not enable model downloads implicitly. |
| Service HTTP/timeout/response/model errors | Check the service's availability, auth reference and declared response contract. Preserve fallback labels; do not manufacture semantic scores. |

Example authorization configuration, using the endpoint actually declared by the registered index:

```powershell
book-agent configure "<book-id>" --query-auth-env "BOOK_QUERY_KEY" --allow-remote-query --allow-query-endpoint "https://<reviewed-host>/<declared-query-endpoint>" --json
```

That command authorizes transmission of the question. A manifest URL alone does not authorize it. Select `--vector-search online` when that route is wanted. SiliconFlow is optional and uses the user's own account for packages declaring its original query contract; no shared credential is delivered. The project has no repair workflow that sends the whole book for new document embeddings.

To use delivered weights offline:

```powershell
book-agent install-query-model "<book-id>" --model-dir "<weights-directory>" --json
book-agent configure "<book-id>" --vector-search offline --query-model-path "<weights-directory>" --json
```

The original compatible weight directory is shared once across all books using that same index contract. Its SHA-256 receipt is portable; update configured paths after moving it. Validation never silently downloads weights; binding requires `configure --query-model-path`. `--download` is an explicit optional request to obtain the inherited original checkpoint. The standard binary provides lexical/HTTP retrieval; local neural execution additionally needs the Python `local-query` extra. Missing optional dependencies or weights do not require a new embedding model or document vector rebuild.

To return to the default route:

```powershell
book-agent configure "<book-id>" --vector-search none --json
```

## Reranking

`rerank_requested=true` and `rerank_applied=false` identify an attempted or configured rerank that was not successfully applied. The default error policy keeps candidates. `--on-reranker-error strict` makes reranker failure an error.

`reranker_consent`/`reranker_endpoint_not_allowed` require explicit authorization for the reviewed endpoint; remote reranking sends the question and candidate text. `reranker_credential` requires a valid protected environment reference. HTTP 401/429 and timeouts require service/auth/rate checks. Invalid indexes, duplicate entries and nonfinite scores indicate a provider contract failure. `reranker_local_model_missing` or `reranker_dependency` requires an existing compatible CrossEncoder model and reviewed optional dependency; automatic model download is disabled.

```powershell
book-agent configure "<book-id>" --reranker none --json
```

Switching rerank configuration does not change existing document vectors.

## Source and visual evidence

Source version mismatch means the locator belongs to different source bytes. Locate again against the registered publication after verifying/rebinding a matching book. A PDF locator uses zero-based physical `page_index`; do not confuse it with a printed page label. Ambiguous alignment stays ambiguous. Use additional source hints or bounded text inspection before declaring a definitive page citation.

For render pixel/byte limits, lower DPI or crop within the page. EPUB images must belong to the requested original chapter/manifest; arbitrary archive members and external URLs are rejected. SVG rendering is not currently supported by the EPUB raster-image reader.

A generated PNG/resource proves rendering and delivery only when actual content is returned. A path does not prove the host/model inspected pixels. If a host cannot carry MCP images or the model cannot interpret them, state the limit and provide available source text/locator evidence. Do not infer a number from a Skill summary, missing figure caption, or OCR alone.

## Host installation

Use a dry run before diagnosing host targets:

```powershell
book-agent install-host "<book-id>" --host codex --dry-run --json
book-agent install-host "<book-id>" --host codex --home ".\BookAgentChecks\IsolatedHome" --dry-run --json
book-agent uninstall-host "<book-id>" --host codex --dry-run --json
```

`host_config_invalid` preserves the malformed existing config; repair its syntax before applying. `host_mcp_conflict` preserves a different existing entry. `host_skill_conflict` preserves a different existing wrapper/generic destination. `host_command_spaces` follows the current TRAE parser restriction: select a verified executable path without spaces. Do not join argv into a shell command as a workaround.

`host_install_locked` indicates a cooperating writer or a stale lock. `host_concurrent_change` means the target changed after the plan; inspect and regenerate the plan. `host_manifest_path` rejects unexpected ownership targets. Uninstall reports modified owned files/entries as preserved conflicts. Keep or explicitly reconcile those user edits before requesting removal again. Backups are retained, and an entire old config is never restored over newer unrelated settings automatically.

WorkBuddy Skill ZIP generation still needs UI import. TRAE project MCP still needs its Settings switch; global MCP is a manual UI step unless an explicit public config path is selected. Cherry Studio is an MCP configuration artifact/manual UI integration with native Skill automatic discovery and its current stdio parser unverified. See [host documentation](hosts.md) for the checked official sources.

## Runtime bootstrap

The runtime Python distribution is `prebuilt-book-agent`; the command is `book-agent`. Version **0.1.0** is pinned in the reviewed Skill bootstrap. A manifest/source/wheel hash mismatch stops before installation. Supply the correct local source archive and approved wheel set, and obtain the expected manifest hash through a trusted delivery channel.

Offline bootstrap uses no package index. If dependencies are absent, supply a reviewed dependency-complete wheelhouse plus its artifact hashes. It never silently goes online. An unrelated existing virtual environment is refused. See [deployment](deployment.md).

After repair, record the achieved acceptance stage accurately: generated config, written config, MCP handshake, tool call, real agent answer, or real agent visual evidence. Isolated unit tests and mocked service tests do not establish real host or online service acceptance.