Project Hub - Fehlerbehebung

English Version

← Zurück zur Übersicht

Einrichtung und Server

Die Tools des MCP-Servers sind nicht verfügbar

Ursache ist meist, dass das virtuelle Environment oder die Pakete fehlen. Führe /project-hub:setup aus und starte Claude Code neu. /project-hub:session-start meldet "Setup unvollständig", wenn venv, config.yaml oder die Python-Abhängigkeiten fehlen.

Der Server läuft mit veralteten Paketen

Ein virtuelles Environment aus der Zeit vor dem Wechsel auf mcp 2.x erkennt session-start an einer fehlenden Komponente. /project-hub:setup synchronisiert die Pakete erneut und entfernt das alte fastmcp.

Setup scheitert unter Windows mit Exit-Code 49

Das ist der Microsoft-Store-Platzhalter für python. Der Skill probiert danach py -3 und bekannte Installationspfade. Findet er nichts, installierst Du Python 3.11 oder neuer von python.org mit der Option, python.exe zum PATH hinzuzufügen.

Konfigurationsänderungen greifen nicht

Der Server liest config.yaml nur beim Start. Starte Claude Code nach einer Änderung neu.

Datenbank

"database is locked"

Der Server unternimmt bis zu fünf Versuche (vier Wiederholungen) mit wachsender Wartezeit. Bleibt der Fehler, schreibt gerade ein anderer Prozess oder die Datenbank liegt auf einem langsamen Netzwerk-Share. Schließe andere Sessions, die dieselbe Datenbank nutzen, und versuche es erneut.

Verdacht auf beschädigte Datenbank bei Cloud-Sync

Liegt db_path in Dropbox, OneDrive, Google Drive oder iCloud, kann die Datenbank unbemerkt beschädigt werden. Verschiebe sie auf einen lokalen Pfad oder einen echten Netzwerk-Share und stelle sie aus einem Backup oder einem Projekt-Export wieder her.

Das aktive Projekt wechselt von allein

Die aktive Auswahl ist ein einzelner Eintrag in der Datenbank. Mehrere Claude-Sessions oder Personen, die dieselbe Datenbank nutzen, überschreiben ihn gegenseitig. Lade das Projekt mit /project-hub:resume neu.

Projekte, Kontakte und Notizen

"A project with slug ... already exists"

Der Slug entsteht aus dem Namen. Wähle einen anderen Namen oder arbeite mit dem vorhandenen Projekt weiter.

Kontakt wird als Duplikat abgelehnt

• "A shared contact with this name or email already exists": Ein geteilter Kontakt gleichen Namens oder gleicher E-Mail-Adresse existiert, auch bei abweichender Schreibweise. Aktualisiere den vorhandenen Kontakt oder nutze ihn direkt, er ist in allen Projekten sichtbar.
• "A shared contact with a very similar name already exists": Der Name ähnelt einem geteilten Kontakt. Handelt es sich um eine andere Person, bestätigst Du das ausdrücklich, und der Kontakt wird mit force angelegt.
• "External contacts cannot be shared": Externe Kontakte bleiben projektspezifisch.

Eine Notiz-Änderung erscheint nicht in der Markdown-Datei

Das ist erwartetes Verhalten: Änderungen betreffen nur die Datenbank, die Datei im Docs-Ordner bleibt alt. Maßgeblich sind die Datenbank, Berichte und Suche. Siehe Technische Details.

Ein Feld lässt sich nicht leeren

Aktualisierungen schreiben nur nicht leere Werte. Ein leerer Wert lässt das Feld unverändert, es lässt sich nur durch anderen Text überschreiben.

Zwei Notizen, aber nur eine Markdown-Datei

Der Dateiname ergibt sich aus Zielordner, Datum und Titel-Slug, nicht aus dem Notiztyp. Notizen mit gleichem Titel am selben Tag teilen sich daher eine Datei, wenn sie im selben Ordner landen. Das gilt auch für unterschiedliche Typen: eine note und eine decision liegen beide in misc/. Der Titel-Slug ist auf 50 Zeichen gekürzt, deshalb können auch verschiedene lange Titel mit gleichem Anfang kollidieren. Beide Notizen bleiben in der Datenbank, nur die Markdown-Datei der älteren wird überschrieben. Setze ein Datum oder einen eindeutigen Zusatz an den Anfang des Titels.

"Kein aktives Projekt"

Die meisten Skills brauchen ein geladenes Projekt. Nutze /project-hub:resume <Name> oder /project-hub:new-project.

Suche findet "Ärger" nicht mit "ärger"

Die Suche ignoriert Groß- und Kleinschreibung nur bei ASCII-Buchstaben. Umlaute müssen in der Schreibweise übereinstimmen. Außerdem wirken % und _ im Suchbegriff als Platzhalter.

Anhänge

Fehlt neben einem PDF oder Word-Dokument die .md-Datei, ist die Umwandlung fehlgeschlagen oder übersprungen worden, der Anhang selbst ist trotzdem gespeichert.

Wissensdokumente

Beim Laden eines Projekts erscheinen keine Wissensdokumente

• Bei Projekten vom Typ generic lädt resume keine Wissensdokumente. Mit /project-hub:knowledge siehst Du, was installiert ist.
• Die Dateien müssen unter ~/.project-hub/knowledge/<projekttyp>/ liegen und auf .md enden. Fehlen sie, installiert /project-hub:knowledge sync die Vorlagen.

vacation-handover bricht ab

Für den Projekttyp existiert kein Dokument vacation-handover. Lege es mit /project-hub:knowledge update vacation-handover an. Eine Vorlage liefert das Plugin nur für merchant-onboarding mit.

Export und Import

• "Unsupported export_version": Die Datei stammt aus einer inkompatiblen Plugin-Version und lässt sich nicht importieren.
• Import wird mit skip abgebrochen: Ein Projekt mit diesem Slug existiert. Wähle rename, oder overwrite, wenn das vorhandene Projekt ersetzt werden soll.
• Achtung bei overwrite: Der Import löscht das vorhandene Projekt samt Kontakten und Notizen und entfernt außerdem seinen gesamten Docs-Ordner von der Festplatte. Die Markdown-Dateien der Notizen und alle Anhangsdateien sind danach weg. Sichere den Ordner vorher, wenn Du ihn noch brauchst.
• Angehängte Dateien fehlen nach dem Import: Anhangsdateien sind nicht Teil des Exports.

Berichte

• Der Bericht öffnet sich nicht automatisch: Der Skill nennt immer den Dateipfad, öffne die Datei manuell im Browser.
• Die Diagramme fehlen: Die Bibliothek wird von cdn.jsdelivr.net geladen und braucht eine Internetverbindung.
• Erledigte Aufgaben erscheinen unter "Offene Aufgaben": Der Bericht listet alle Notizen vom Typ action-item ohne Erledigt-Filter.