Guides

Troubleshooting

Common issues and their fixes — from missing SQLite to model download failures.

First stop: gno doctor

gno doctor

gno doctor runs every health check GNO knows how to run and prints a report. Nine out of ten problems get diagnosed right here. Read its output carefully before anything else.

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.
• 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>.

Results feel stale after editing

Re-scan the index:

gno update

Or run gno daemon in the background for continuous indexing.

Results feel off after switching models

Vector-based search uses the embedding model that was active when the index was built. After switching embeddings, re-embed:

gno embed # re-embed everything
gno embed notes # or one collection
gno collection clear-embeddings notes # drop stale vectors

Still stuck?

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