Troubleshooting
What you see, what it usually means, and what to do, for install, sign-in, the model, connectors, documents, agents and proxies.
Find the symptom, read the cause, apply the fix. If nothing here matches, look at the Activity page (admins) and the container logs (docker compose logs app), then open an issue with what you saw.
Install and start#
| You see | Cause | Fix |
|---|---|---|
docker compose up stops with set DB_PASSWORD in .env (or APP_DB_PASSWORD) | A required value is missing. | Copy .env.example to .env and fill in the REQUIRED values: DB_PASSWORD, APP_DB_PASSWORD, SECRET_KEY, INITIAL_ADMIN_PASSWORD. |
The page does not load at http://localhost:8080 | The app is still starting (the health check takes up to a minute), the port is in use, or the app is bound to another address. | docker compose ps should show app as healthy. Change HTTP_PORT if the port is taken. By default the app listens on 127.0.0.1 only: set HTTP_BIND=0.0.0.0 only if you expose it without a proxy. |
| You cannot sign in as the first administrator | INITIAL_ADMIN_USERNAME and INITIAL_ADMIN_PASSWORD are used only when there are no users yet. Changing them later does nothing. | Sign in with the values that were in .env the first time. Another administrator can set a new password on Users & access > Users. Keep a second administrator for this reason: there is no email reset. |
| locked, even with the right password | Five failed sign-ins for a username, or thirty from one address, lock sign-in for 15 minutes. | Wait 15 minutes. |
| Uploading a document fails with the file could not be stored (PermissionError … Permission denied: '/app/data/library') | The ./data folder next to docker-compose.yml is owned by another user. The app runs as user id 1000. | sudo chown -R 1000:1000 ./data, then retry the source. |
| Everything works, but the Knowledge menu is missing | The library is off (Settings > Library), or a proxy or CDN cached an old error for /api/status. | Turn the library on. Behind Cloudflare or another CDN, never cache /api/ or /mcp: add a rule that bypasses the cache for those paths, then purge the cache. |
A change in .env has no effect | The value is also set on the Settings page, which wins over .env. | Open the setting: each row says whether its value comes from the page, .env or the default. Reset removes the page value. |
Sign-in, users and limits#
| You see | Cause | Fix |
|---|---|---|
| try again in N s (HTTP 429) | A rate limit: per client address for the API and MCP, for sign-in, and per user for Alfred and heavy actions. | Wait, or raise RATE_PER_S, RATE_BURST, LOGIN_PER_MIN, ALFRED_PER_MIN or INGEST_PER_MIN. |
| Everyone is rate limited as one client | The app sees the proxy's address for every request. | Set CLIENT_IP_HEADER and TRUSTED_PROXIES to match your proxy: Running behind a proxy. |
| A user cannot add or approve documents | Adding documents needs the editor role and a write or manage grant on the collection. | Tick editor on the user, and grant access on the collection's access table. |
| A new password is refused | Passwords need at least 12 characters and cannot be the username. | Choose a longer one. |
The model and Excel#
| You see | Cause | Fix |
|---|---|---|
| The upload report says sheet "Values" is missing: start from the template | A workbook must contain all nine sheets, even empty ones: Instructions, Model, Entities, Fields, Values, Filters, Checks, Relationships, Examples. | Start from the downloaded template, or add the missing sheets with their header row. |
| the Model sheet needs a name | The Model sheet is read from row 2: row 1 is a header. | Add a header row, then name in the first column and the model's name in the second. |
| unknown entity "x" (not in the Entities sheet) | entity_key and applies_to use the entity key; references, and from and to in Relationships, use the entity name. | Check which one the column expects: the column reference says. |
| entity name "x" is also used by y | Names must be unique, because relationships refer to entities by name. | Rename one. |
| The upload creates a draft but you wanted to keep an existing one | An existing draft is replaced only when you choose to. | Read the confirmation on the Excel card before you accept. |
| Validate lists errors | A reference does not resolve, a required property is missing, a value is not on its allowed list, a restricted field has agent access other than none, or a name is duplicated. | Fix them in the draft. SQL that does not run on the connected database is only advice. |
| Publish fails | Validation failed, or the search index could not be built or embedded. | The draft stays a draft and the embeddings already computed are kept. Read the message, fix it and press Publish again. |
| there is no published ontology to build the demo database from: publish one first | The demo database is generated from the published model. | Publish a version, then build it. |
| The Model check shows Attention | The rule text and the physical schema do not fully line up. These are usually questions for modellers, not data bugs. | Open the item: it carries the SQL that produced it. On the demo database, structure and joins always hold, but your data-quality rules may not: generated data does not know your business rules. |
Connectors#
| You see | Cause | Fix |
|---|---|---|
| Test cannot connect | The host is not reachable from inside the app container. localhost is the container itself. | Use a host name or address the container can reach (for a database on the same machine, its address on the Docker network or the host's address). Check the port and the SSL mode. |
| A warning that the account can write | The connector test checks the account's privileges. | Create a read-only account: Connect your data. Queries are forced read-only anyway, but a read-only account is the real protection. |
| the stored password cannot be decrypted (SECRET_KEY changed?) | SECRET_KEY changed after the password was saved. | Enter the connector password again, and the AI key and S3 secret if you set them on the Settings page. |
| A SQLite or DuckDB file is refused | The file must live under CONNECTOR_FILES_DIR (default /app/data, which is ./data on the host), and not under data/library. | Move the file there and use its path. |
| the app's own database or a link-local address is refused | A connector cannot point at the app's own database or at link-local or cloud-metadata addresses. | Point it at your own database. |
| Agents cannot read rows, but can plan | Agents may read rows is off on the connector, or the token lacks the data entitlement. | Turn it on per connector, and grant data to the token. |
Documents and the library#
| You see | Cause | Fix |
|---|---|---|
| A source stays waiting | No worker is free, or the queue is busy. | By default the web app runs two workers (LIBRARY_WORKERS). For many documents add the worker container. |
| A source is ready but has no source page or topics | No AI endpoint is configured, or the collection's Documents may be sent to the AI model switch is off. The document is still stored and searchable by words and meaning. | Configure the endpoint (Settings > AI) or turn the switch on. Then regenerate the page. |
| A source failed | The file has no readable text, is a legacy format, or could not be opened. | Read the reason on the source. .doc, .ppt, .xls and .rtf are not accepted: save them as .docx, .pptx, .xlsx. Scanned pages need a vision-capable model (Settings > AI, Model that reads images). The same file cannot be added twice to a collection. Use Retry after fixing it. |
| A web page is empty or nearly so | The page builds its content with JavaScript. | Enable the browser service. Pages behind a login are not fetched. |
| A web address is refused | Only public http and https addresses are fetched; private, loopback and metadata addresses are refused, and so are addresses with a user name or password. | To read an intranet, list its hosts in Settings > Web capture (and in FETCH_ALLOWED_HOSTS for the browser service). |
| A change never shows up on a topic | It contradicts a published fact, or looks like a duplicate, so it is held. | Open Knowledge > Review: compare both versions and approve, reject or merge. Readers see the old page until then. |
| needs review on a source page | The checker still disagrees with the page after its correction rounds. | Read the objections next to the page and approve it, or have it written again. |
| An agent cannot see a collection | Agents see a collection only if their token holds a grant on it and Agents may read this collection is on. A collection it may not read gives the same answer as one that does not exist. | Grant read access to the token on the collection's access table. |
| Alfred will not read a collection | Alfred also needs Documents may be sent to the AI model, because it sends what it reads to its model. | Turn it on for that collection. |
| A search returns nothing, or finds only exact words | Embeddings are missing (for example after changing the embedding model), or you are running with keyword search only. | Settings > Maintenance > Rebuild search index. |
You changed EMBEDDING_MODEL or EMBEDDING_DIM | The vector tables are created for one size. | Starting with a different size converts them, empties the vectors and recomputes them in the background. Wait for it to finish. |
Agents and Alfred#
| You see | Cause | Fix |
|---|---|---|
HTTP 401 from /mcp | No token, a revoked token, or a wrong header. | Send Authorization: Bearer <token>. A new token is shown once; create another if you lost it. |
| The agent sees six tools, not sixteen | The ten library_ tools appear only to a token with a grant on at least one collection. | Grant the token read access on a collection. |
Values come back as h_ followed by letters and digits | The field is masked for this credential: callers without the class get a stable hash. | Grant the entitlement (confidential or personal) if appropriate. Masked columns can still be counted, grouped and joined. |
| query_data refuses | The token lacks the data entitlement (new tokens start without it), or the connector forbids rows for agents. | Grant data on Users & access > Tokens & MCP. |
A result is cut with a note about truncated | query_data returns at most AGENT_MAX_ROWS rows (default 100) and does not page. | Aggregate or filter in SQL. The note gives the total. |
| Alfred is missing or says it is off | No AI endpoint. | Settings > AI: set the address, key and model, and press Test the endpoint. |
| Alfred answers from a partial search | It used all its lookups for the question (ALFRED_MAX_LOOKUPS, default 10) and answered from what it had found. The Activity page marks such a question. | Ask a narrower question, or raise the limit. |
Proxies and CDNs#
| You see | Cause | Fix |
|---|---|---|
| Sign-in or the UI works, but the API shows stale errors | A CDN or proxy cached an API response. | Bypass the cache for /api/ and /mcp. |
| Cookies are not kept over HTTPS | The app does not know the request came over HTTPS. | Terminate TLS in a trusted proxy and list it in TRUSTED_PROXIES: the app marks cookies Secure when the trusted proxy says so. |
| A browser console message about an inline script blocked by the Content-Security-Policy | A CDN injected a script into the page. The app's policy forbids inline scripts. | It is harmless to the app. Disable the CDN's script injection if you want the console quiet. |