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