Fehlerbehebung und Randfälle
Diese Seite geht über die Grundlagen der Anleitung hinaus und erklärt die Randfälle: was einzelne Fehlermeldungen wirklich bedeuten, warum die Suche sich manchmal seltsam verhält und wie der Import an Grenzfällen scheitert. Jeder Punkt nennt die Ursache, nicht nur das Symptom.
Upload und Import
„Keine OKF-Konzepte in der Datei gefunden". Der Parser hat keine lesbare Konzeptdatei gefunden. Ein ZIP braucht echte .md-Dateien; ein Archiv nur aus Bildern, PDFs oder Anhängen reicht nicht. Enthält das ZIP ausschließlich okf.md, INDEX.md oder README.md, ist es ebenfalls leer aus Sicht des Parsers – diese Aggregatdateien werden absichtlich übersprungen.
„OKF konnte nicht geparst werden". Das Format wird über die ersten Bytes erkannt, nicht über die Dateiendung: PK steht für ZIP, ein führendes [ oder { für JSON, alles andere gilt als einzelnes Markdown. Ein als .zip benanntes, aber beschädigtes Archiv fällt hier durch. Prüfen Sie, ob die Datei wirklich ein gültiges ZIP ist.
„Bitte ein ZIP-Archiv des Exports hochladen". Der Import-Weg (nicht der OKF-Upload) erwartet ausschließlich ein ZIP. Der Server erkennt das an den Magic Bytes; eine einzelne Markdown- oder HTML-Datei wird hier abgelehnt. Nutzen Sie für ein fertiges Einzelkonzept den normalen OKF-Upload.
„Quelle nicht erkannt" (SOURCE_UNKNOWN). Die automatische Erkennung sucht nach charakteristischen Spuren: Confluence an entities.xml oder exportDescriptor.properties, Notion an den 32-stelligen Hex-IDs in Dateinamen, Logseq an journals/ oder pages/, Obsidian an .obsidian/. Fehlen diese, wählen Sie die Quelle im Dialog manuell. Häufige Ursache: Das ZIP wurde umgepackt und hat seine ursprüngliche Ordnerstruktur verloren.
Nach dem Import sind Links kaputt. Der Importer schreibt nur Ziele um, die er eindeutig über Dateiname oder Seitentitel findet. Wikilinks und lokale .md/.html-Links auf umbenannte Seiten, doppelte Titel oder nicht exportierte Inhalte landen als LINK_TARGET_MISSING im Bericht. In OKF ist ein kaputter Link kein Fehler – er darf auf noch nicht geschriebenes Wissen zeigen. Prüfen Sie die Liste trotzdem, viele sind echte Tippfehler.
Zwei Seiten mit gleichem Titel (RENAMED). Der Importer vergibt eindeutige bundle-relative Pfade. Kollidieren zwei Titel, hängt er -2, -3 an und meldet RENAMED. Das ist kein Fehler, nur ein Hinweis, dass zwei Quellen denselben Slug ergeben hätten.
Suche und Retrieval
Die Suche findet einen Begriff im Fließtext nicht. Die Bibliothekssuche nutzt Titel, Beschreibung und Tags – nicht den vollständigen Body. Das ist Absicht: Viele importierte Konzepte teilen einen wiederkehrenden Textblock, der eine reine Volltextsuche unbrauchbar machen würde. Ergänzen Sie den Begriff in einer aussagekräftigen Beschreibung oder als Tag. Für inhaltliche Fragen nutzen Sie den RAG-Assistenten.
Der Assistent findet vorhandene Information nicht – mal so, mal so. Der Hub sucht zuerst semantisch mit einem lokalen Embedding-Modell. Ist dessen Index für ein frisch hochgeladenes Bundle noch nicht fertig, fällt er automatisch auf eine feldgewichtete Stichwortsuche zurück, bei der Titel und Beschreibung stark gewichtet werden. Direkt nach dem Upload kann dieselbe Frage deshalb ein anderes Ergebnis liefern als eine Minute später, wenn der Vektorindex steht. Warten Sie kurz und fragen Sie erneut.
Die Antwort enthält keine Quellen. Der Hub listet nur Quellen, die das Modell tatsächlich nummeriert zitiert hat. Zitiert es keine, formulieren Sie die Frage konkreter. Und beachten Sie: Der Assistent nennt bewusst keine externe URL – Zitate öffnen den OKF-Auszug innerhalb des Hub, nie die Originalseite. Das ist eine Design-Entscheidung, kein Fehler.
„RAG nicht konfiguriert". Der Chat braucht einen konfigurierten Modellzugang. Ist die Verbindung zum Anbieter serverseitig nicht gesetzt, antwortet der Endpunkt mit diesem Hinweis. Das ist eine Betriebsmeldung, kein Nutzerfehler.
Konto, Limits, Sitzung
„Monatslimit erreicht". Kostenlos sind standardmäßig drei Uploads oder Importe pro Kalendermonat. Gezählt werden Vorgänge, nicht gespeicherte Bundles – ein gelöschter Upload gibt sein Kontingent nicht zurück. Der maßgebliche Wert steht in der App, weil das Limit serverseitig konfigurierbar ist. Demo-Daten laden zählt nicht.
„Sitzung abgelaufen". Die Anmeldesitzung gilt bis zu 30 Tage und liegt im lokalen Speicher des Browsers. Nach Ablauf, nach dem Löschen der Browserdaten oder auf einem anderen Gerät müssen Sie sich neu anmelden. Der Chat-Verlauf (bis zu 25 Einträge) liegt ebenfalls lokal und wird nicht zwischen Geräten synchronisiert.
Ich habe versehentlich gelöscht. Löschen ist in der App nicht rückgängig zu machen – es gibt keine Versionshistorie. Löschen entfernt Chiffretext, Vektorindex und Metadaten. Importieren Sie eine Sicherung neu; der erneute Upload zählt zum Monatslimit. Bewahren Sie deshalb Ihre Originaldateien auf, zumal ein vollständiger Bundle-Export in der Oberfläche derzeit nicht verfügbar ist.
Randfälle für Entwickler
„vector index size mismatch". Der gespeicherte Vektorindex passt nicht mehr zur Zahl der Konzepte – typisch, nachdem Konzepte bearbeitet oder gelöscht wurden. Der Hub verwirft den alten Index und baut ihn neu; die nächste Frage kann kurz langsamer sein. Kein Datenverlust.
Ein reload-tes Bundle wird falsch geparst? Das kann nicht passieren, weil die Formaterkennung über den Inhalt läuft, nicht über den Namen. Ein gespeichertes Bundle trägt oft einen Anzeigenamen ohne Endung (etwa „Demo OKF (DE)"); die Magic-Byte-Erkennung liest es trotzdem korrekt als ZIP oder JSON.
Weiter im Thema
Die Grundlagen und die Basis-Fehlerbehebung stehen in der Anleitung. Wie Speicherung und Verschlüsselung funktionieren, klärt die Verschlüsselungsseite. Was sich zuletzt geändert hat, führt der 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.