Troubleshooting

Troubleshooting

Start with strata_admin_health. It checks the database connection, pgvector and the schemas in one call, and reports the embedding checks (embedding), the SQL tools (sql_tools), the local-only switch and the outbound providers. From a terminal, uv run stratakb add <folder> reports config, local-only, database and schema problems through its message and exit code.

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 -->|"overall ok, but database.schemas lacks one"| sm["A schema is missing"]
    h -->|"embedding degraded"| em["Embedding check failed"]
    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"]

Loading

The client says the server failed to start

• Local-only refusal. With STRATA_LOCAL_ONLY=true the server refuses to start while a setting would send content off this machine. The error names each setting; unset it or turn the switch off. stratakb add refuses the same way (exit 2, reason local_only) when the embedding path would leave the machine. With the switch off, an unknown EMBEDDING_BACKEND, or openai with neither OPENAI_API_KEY nor EMBEDDING_BASE_URL, does not stop the server: the tools that embed return an error naming the setting, and stratakb add refuses with reason embedding_setup. See Where your data goes.
• 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 --directory in your MCP configuration must point at the cloned folder.

The server answers its client at once and loads the embedding model in the background, so a slow model download no longer makes the start time out. The first search waits for the model instead; if it times out, wait for the download (about 420 MB) and ask again, or run uv run stratakb add once beforehand so the model is cached.

My settings are ignored

Settings are no longer read from ./.env. When the server finds a ./.env it does not read, it logs dotenv_not_read at startup, and stratakb add prints the same hint. Move the settings to your user config.env, or set STRATAKB_CONFIG=.env. See Installation for the file locations and the order.

When STRATAKB_CONFIG names a file that does not exist, the server logs config_file_not_found and carries on without it; stratakb add refuses with config_not_found (exit code 2). Fix the path or unset STRATAKB_CONFIG.

A config file edited while the server runs changes nothing for strata_admin_health, strata_search, strata_ask, strata_ingest_documents, strata_apply_preset, query rewriting or the query embedding until you restart the server. That includes STRATA_LOCAL_ONLY for the outbound providers: turning it on stops them only after a restart, though a model the server has not loaded yet is kept from downloading at once. The user and role (STRATA_USER, STRATA_ROLE) are read once, when the server starts: restart it after changing either.

Connection refused on port 5433

• Start the database: uv run stratakb db up. It starts a stopped container and keeps its data. With the development docker-compose.yml, check docker compose ps instead.
• stratakb db up says the port is in use: another database holds 5433, often the docker compose container strata-postgres (Docker Desktop says "Ports are not available"). Stop one of them, or pass --port when the container is first created. Both containers start again with Docker unless they were stopped, so with both on 5433 they race for the port at every Docker start; stop the one you don't use (stratakb db down or docker compose stop) and it stays stopped.
• On Windows, use 127.0.0.1 rather than localhost in the database URLs. localhost can resolve to the IPv6 address ::1, which some Docker setups don't forward.
• stratakb add exits with code 3 (db_unreachable) when it can't reach the database. The message names the database it tried and the config files it read; set DATABASE_URL or STRATAKB_CONFIG, or run stratakb db up, as the message says.

A schema is missing

The server brings the schema up to date by itself: at startup, and before stratakb add writes anything, it applies every numbered migration the database is missing and records it in strata_core.schema_migrations. If a schema is missing, restart the server once the database is up, or run stratakb add. strata_admin_health does not flag this: overall stays ok, so compare database.schemas with strata_core, strata_vectors and strata_learning.

If the database user may not change the schema, the server logs db_migration_failed and stratakb add exits with code 3 (schema). The message names the SQL file to apply as the database owner with psql -f, or the privilege the user is missing. A schema update that waits more than 30 seconds for a lock (another StrataKB process updating the schema, or a long session on a table it changes) stops and names the lock; run it again once the other process is done. When the startup update was skipped (the database was down) or failed, the first strata_ask tries it again, and an extractive answer that cannot get the update fails with the same message, naming the file and the fix. A failed update is tried again at most every 10 seconds.

If it refuses to set up the schema in postgres or a template… database, DATABASE_URL names the wrong database. Create one for StrataKB (CREATE DATABASE strata;) and point DATABASE_URL at it; the log line setting_up_database (and stratakb add on stderr) shows which host:port/database it is about to set up (unknown host when the URL cannot be read safely: percent-encode the password). The same target, the one asyncpg connects to, shows in the creating_db_pool log line (key target) and in the "Can't reach the database at …" messages of stratakb add and stratakb receipt: with a host and port in the query string it shows those, and a multi-host URL shows each host with its port. A port outside 1-65535, another scheme, an empty host in a list, or an @ in the URL's path or query also shows unknown host.

If the update keeps saying the read-only grants are still there after 06_readonly_grants.sql ran, strata_readonly gets that access another way: from a PUBLIC grant or a role it belongs to, such as pg_read_all_data. 06 does not remove those; revoke them by hand as the database owner.

An older layer lost a folder after upgrading

A 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 embedding check failed

strata_admin_health shows overall: degraded and, under embedding, a model that is missing or a vector_column that is a mismatch. The message names the setting to change:

• Model missing: the server in EMBEDDING_BASE_URL does not list EMBEDDING_MODEL. Pull the model, or fix the name. Some servers serve any requested name under one listed file name; if embedding works, that report can be ignored.
• Column mismatch: EMBEDDING_DIMENSIONS differs from the vector(...) column. Pick a model of that size, or change both and re-embed.

Restart StrataKB after the fix to check again. unchecked means the check could not run (for example, the server was not up yet) and does not degrade health.

Extractive mode needs the reranker model

Extractive answers score sentences with the reranking model, even with RERANKING_ENABLED=false. When it cannot load, strata_ask reports this error. On a machine that may download, run uv run hf download cross-encoder/ms-marco-MiniLM-L-6-v2, or set RERANKING_MODEL to a folder that holds the model.

A PDF ingested but returns nothing

The PDF is probably scanned, so it has little or no text layer. A PDF where more than half the pages hold an image and under 200 characters of text is stored and reported as flagged (files_flagged, reason probably_scanned); one with no text at all is skipped (no_text). Run it through an OCR tool such as ocrmypdf and ingest the result.

The PEPs example checks out nothing

In Git Bash on Windows, Git Bash rewrites the /peps/... paths of the sparse-checkout command. Put MSYS_NO_PATHCONV=1 in front of it:

MSYS_NO_PATHCONV=1 git -C examples/peps/source sparse-checkout set --no-cone /peps/pep-0008.rst /peps/pep-0020.rst /peps/pep-0257.rst /peps/pep-0484.rst /peps/pep-0572.rst /peps/pep-0634.rst /peps/pep-0695.rst /peps/pep-0723.rst

Every question goes to the same layer

One of that layer's routing patterns matches common words. Make the patterns more specific; see Layers and Presets.

Results look out of date

Results are cached for CACHE_TTL_SECONDS (600 by default). A change to any layer, such as an ingestion, clears the whole cache in every process that serves it (checked at most every 2 seconds). To rule the cache out, set CACHE_ENABLED=false.

Still stuck

Set LOG_LEVEL=DEBUG and open a bug report. Include the versions and the log lines around the error, after removing anything private.