Repository navigation
Troubleshooting
Start with strata_admin_health. It checks the database connection, pgvector and the schemas in one call.
flowchart TD
s{"Does the server start?"} -->|no| st["Server failed to start"]
s -->|yes| h{"strata_admin_health OK?"}
h -->|"database unreachable"| cr["Connection refused"]
h -->|"schema missing"| sm["A schema is missing"]
h -->|yes| r{"What is wrong with results?"}
r -->|"nothing from a PDF"| pdf["PDF returns nothing"]
r -->|"always one layer"| rt["Same layer every time"]
r -->|"old content"| ca["Results out of date"]
- Timeout. The first start downloads the embedding model. Raise your client's MCP startup timeout, or run a search once from the command line so the model is cached.
-
Something printed to stdout. The MCP protocol uses stdout, and logs go to stderr. If you added a
print()while debugging, remove it. -
Wrong path. The
--directoryin your MCP configuration must point at the cloned folder.
- Check that the container is up:
docker compose ps. - On Windows, use
127.0.0.1rather thanlocalhostin the database URLs.localhostcan resolve to the IPv6 address::1, which some Docker setups don't forward.
The db/*.sql scripts run only when the data volume is created. If you started the container before a schema was added, apply it by hand:
docker compose exec -T postgres psql -U strata -d strata -f /docker-entrypoint-initdb.d/02_learning.sqlA layer ingested by a version before file tracking is rebuilt on its next ingestion, and that run keeps only the folder it ingests. Ingest each of the layer's other folders once more. Applying a preset rebuilds every folder, so preset layers are not affected. The server adds the tracking table to an existing database by itself at startup; if its database user may not change the schema, the error names the SQL file to run as the database owner.
The PDF is probably scanned, so it has no text layer. Run it through an OCR tool such as ocrmypdf and ingest the result.
One of that layer's routing patterns matches common words. Make the patterns more specific; see Layers and Presets.
Results are cached for CACHE_TTL_SECONDS (600 by default). Ingesting into a layer clears that layer's cache. To rule the cache out, set CACHE_ENABLED=false.
Set LOG_LEVEL=DEBUG and open a bug report. Include the versions and the log lines around the error, after removing anything private.
Getting started
Using StrataKB
Reference
Help