Troubleshooting

Doctor output, Homebrew SQLite on macOS, model pulls, stale embeddings, and Windows llama.cpp startup.

First stop: gno doctor

gno doctor

Start here: gno doctor runs the health checks GNO ships, including embedding-fingerprint (current fingerprint, pending/stale chunks, mixed stored groups). Read its output carefully before anything else.

For embedding freshness, look for the embedding-fingerprint check. It reports the current fingerprint, pending/stale chunks, legacy empty-fingerprint vectors, and mixed stored fingerprint groups.

Cloud placeholders skipped under sourceAvailability local

Opt-in sourceAvailability: local (collection config) is distinct from egressPolicy. On tested macOS File Provider layouts it refuses content that would require materialization. Receipts may show CLOUD_PLACEHOLDER, CLOUD_PARTIAL, DATALESS_DIRECTORY, or fail-closed SOURCE_AVAILABILITY_* codes. Indexed descendants under unproven prefixes are preserved. Evidence covers Google Drive, iCloud Drive, and OneDrive only for the tested configuration and both validated immediate SharePoint library roots — not Windows/Linux cloud filesystems. GNO does not pin, evict, or download as product behavior. See Configuration → Source availability.

Retrieval activation is blocked or degraded

Check gno doctor, gno status --json, or the dashboard Health Center. A ready collection has completed a bounded, corpus-derived lexical search and returned its expected document. Semantic search may still be pending independently while models or embeddings are prepared.

• no_documents or no_probe_term — add a supported text document or fix the collection filters, then run gno index <collection> --no-embed.
• index_out_of_sync or retrieval_mismatch — rebuild that collection’s lexical index, then rerun doctor.
• Connector failures — open Web Connectors and run its explicit read-only verification action again after repairing the configured MCP command. Skill installations remain runtime unverifiable; that is not a passed connector proof.
• A truncated connector projection is incomplete by definition. Omitted target/collection pairs have no result, so status stays warning/non-green instead of guessing.
• Wrong workspace in a connector — reinstall it from the intended GNO workspace. The installer pins the active index and absolute config, data, and cache roots; passive status does not rewrite a stale client entry.

Technical integrity boundary: supported GNO writers maintain the FTS synchronization marker transactionally, and database migration validates legacy mirror bodies once before backfilling it. Direct, out-of-band mutation of an FTS body after migration bypasses that owned-writer contract and is not detectable by the metadata-only passive fingerprint. Repair by rebuilding the affected collection; do not edit GNO’s FTS tables directly.

Error: database is locked or exit code 4

Since v1.38.0, concurrent writers queue on one shared write lease. The bare Error: database is locked message no longer appears for CLI/MCP overlap.

Exit code 4 means another writer held the lease past --lock-wait (default 120s). This is contention, not corruption — retry the command. Raise --lock-wait for long reindexes, or pass --no-wait in scripts that prefer failing fast. Reads never take the lease and are never blocked.

chunks deferred by index contention means rerun gno embed after the other writer finishes. On pre-1.38 versions the fix is upgrading.

Vector search fails on macOS

Symptom: gno vsearch or hybrid queries fail with a SQLite extension loading error.

Cause: the stock Apple SQLite doesn’t support loading extensions. GNO needs the Homebrew build.

brew install sqlite3
gno doctor

Models fail to download

Symptom: the first gno query or gno ask stalls during a model pull.

Solutions:

• Run gno models pull explicitly to see real-time progress and errors.
• HTTP rerank endpoints are external services, so model pulls skip them instead of treating them as downloadable GGUF files.
• If you’re offline or behind a firewall, set GNO_NO_AUTO_DOWNLOAD=1 and download model files by hand into the cache.
• Clear a stuck download with gno models clean <preset>.
• If a cached download is reported as non-GGUF or intercepted HTML, fix network access and rerun gno models pull --force.

Results feel stale after editing

Re-scan the index:

gno update

Or run gno daemon in the background for continuous indexing.

Update reports an invalid PDF

The PDF is incomplete or damaged. GNO isolates it as a non-fatal CORRUPT document, continues indexing the collection, and keeps the Web UI available. It does not retry the unchanged file on every update.

qpdf --check /path/to/file.pdf

Replace or re-export the PDF, then run gno update or Update All. A changed source hash makes GNO try the repaired file again.

Results feel off after switching models

Vector-based search uses the embedding model that was active when the index was built. Doctor now makes this visible through the embedding-fingerprint check. After switching embeddings, re-embed:

gno doctor
gno embed # re-embed stale/pending chunks
gno embed notes # or one collection

gno embed retries transient embedding failures within the same run. If doctor still reports stale, legacy, or mixed vectors after a normal embed, force a full refresh:

gno embed --force

gno embed --force uses the same same-run retry path. If a run still fails, rerun with verbose output so GNO prints sample failures and the retry hint:

gno --verbose embed --force

Check which GPU backend is detected

Before forcing a backend, see what node-llama-cpp actually detects. This works on Linux, Windows, and macOS and reports the active GPU backend (CUDA, Vulkan, or Metal), available VRAM, and which prebuilt binary is in use:

bunx --bun node-llama-cpp inspect gpu

(npx --no node-llama-cpp inspect gpu works too.) If CUDA or Vulkan shows as available here but GNO still runs on CPU, the backend is being selected or initialized incorrectly — see below. If it is not available here, the GPU driver or toolchain is the problem, not GNO.

Windows model startup hangs

Symptom: gno index, gno embed, or gno doctor appears stuck while loading node-llama-cpp, often around a Vulkan backend load test.

GNO now defaults to prebuilt local-model backends, times out backend initialization, and retries CPU on Windows when automatic GPU backend selection fails. Run diagnostics first:

gno doctor

To force CPU mode for a constrained Windows machine, run:

GNO_LLAMA_GPU=false gno embed --yes

If CPU embedding still consumes too much memory, keep the adaptive default or set an explicit small context pool. On CPU-only systems, GNO defaults to one context on low-memory Windows machines and at most two contexts elsewhere:

GNO_EMBED_CONTEXTS=1 gno embed --yes

Advanced CPU tuning is available when you want to trade throughput, memory, and per-context parallelism:

GNO_EMBED_CONTEXTS=2 GNO_EMBED_THREADS=4 gno embed --yes
GNO_EMBED_CONTEXT_SIZE=512 gno embed --yes

Only opt into source builds when you intentionally have Visual Studio Build Tools and a working native toolchain:

GNO_LLAMA_BUILD=autoAttempt gno doctor

Still stuck?

• Open an issue: github.com/gmickel/gno/issues
• Include your gno doctor output and the exact command you ran.