Troubleshooting and edge cases
This page goes beyond the basics in the guide and explains the edge cases: what individual error messages really mean, why search sometimes behaves oddly, and how import fails at boundary cases. Each item names the cause, not just the symptom.
Upload and import
"No OKF concepts found in the file." The parser found no readable concept file. A ZIP needs real .md files; an archive of only images, PDFs, or attachments is not enough. If the ZIP contains only okf.md, INDEX.md, or README.md, it is empty from the parser's view – those aggregate files are skipped on purpose.
"OKF could not be parsed." Format is detected by the first bytes, not the extension: PK means ZIP, a leading [ or { means JSON, anything else is treated as a single Markdown file. A file named .zip but corrupt fails here. Check that the file is really a valid ZIP.
"Please upload a ZIP archive of the export." The import path (not the OKF upload) expects a ZIP only. The server detects this by magic bytes; a single Markdown or HTML file is rejected here. For a finished single concept, use the normal OKF upload.
"Source not detected" (SOURCE_UNKNOWN). Auto-detection looks for characteristic traces: Confluence by entities.xml or exportDescriptor.properties, Notion by the 32-character hex IDs in filenames, Logseq by journals/ or pages/, Obsidian by .obsidian/. If these are missing, select the source manually in the dialog. Common cause: the ZIP was repackaged and lost its original folder structure.
Links are broken after import. The importer only rewrites targets it can identify unambiguously by filename or page title. Wiki links and local .md/.html links to renamed pages, duplicate titles, or non-exported content end up as LINK_TARGET_MISSING in the report. In OKF a broken link is not an error – it may point to not-yet-written knowledge. Review the list anyway; many are real typos.
Two pages with the same title (RENAMED). The importer assigns unique bundle-relative paths. If two titles collide, it appends -2, -3 and reports RENAMED. Not an error, just a note that two sources would have produced the same slug.
Search and retrieval
Search does not find a term in the body. Library search uses title, description, and tags – not the full body. This is deliberate: many imported concepts share a recurring text block that would make plain full-text search useless. Add the term to a useful description or tag. For content questions, use the RAG assistant.
The assistant misses existing information – sometimes. The Hub retrieves semantically first, with a local embedding model. If its index for a freshly uploaded bundle is not ready yet, it falls back automatically to field-weighted keyword search that heavily weights title and description. Right after upload, the same question can therefore return a different result than a minute later, once the vector index is built. Wait briefly and ask again.
The answer contains no sources. The Hub lists only sources the model actually cited by number. If it cites none, ask a more focused question. And note: the assistant deliberately names no external URL – citations open the OKF excerpt inside the Hub, never the original page. That is a design choice, not a bug.
"RAG not configured." Chat needs a configured model connection. If the provider link is not set server-side, the endpoint returns this notice. An operational message, not a user error.
Account, limits, session
"Monthly limit reached." The free tier is three uploads or imports per calendar month by default. It counts operations, not stored bundles – a deleted upload does not return its quota. The authoritative value is shown in the app, because the limit is server-configurable. Loading demo data does not count.
"Session expired." The sign-in session lasts up to 30 days and lives in browser local storage. After it expires, after clearing browser data, or on another device, you must sign in again. The chat history (up to 25 entries) is also local and is not synced across devices.
I deleted something by accident. Deletion cannot be undone in the app – there is no version history. Deletion removes ciphertext, vector index, and metadata. Re-import a backup; the new upload counts toward the monthly limit. Keep your original files, especially since a full bundle export is not currently available in the interface.
Developer edge cases
"vector index size mismatch." The stored vector index no longer matches the concept count – typical after concepts were edited or deleted. The Hub discards the old index and rebuilds it; the next question may be briefly slower. No data loss.
Does a reloaded bundle get mis-parsed? It cannot, because format detection runs on content, not name. A stored bundle often carries a display name without an extension (such as "Demo OKF (DE)"); magic-byte detection still reads it correctly as ZIP or JSON.
Continue
The basics and base troubleshooting are in the guide. How storage and encryption work is on the encryption page. What changed most recently is in the changelog.
Fehlermeldungen und Verhalten nach der realen server.js, lib/import.js, lib/okf.js und lib/semantic.js dieses Projekts. / Error messages and behavior per this project's real server.js, lib/import.js, lib/okf.js, and lib/semantic.js.