Project Hub - Troubleshooting

Deutsche Version

← Back to overview

Setup and server

The MCP server's tools are not available

Usually the virtual environment or the packages are missing. Run /project-hub:setup and restart Claude Code. /project-hub:session-start reports "Setup unvollständig" (setup incomplete) if the venv, config.yaml or the Python dependencies are missing.

The server runs with outdated packages

session-start detects a virtual environment from before the switch to mcp 2.x by a missing component. /project-hub:setup syncs the packages again and removes the old fastmcp.

Setup fails on Windows with exit code 49

That is the Microsoft Store placeholder for python. The skill then tries py -3 and known install locations. If it finds nothing, install Python 3.11 or newer from python.org with the option to add python.exe to PATH.

Configuration changes have no effect

The server reads config.yaml only at startup. Restart Claude Code after a change.

Database

"database is locked"

The server makes up to five attempts (four retries) with increasing wait times. If the error persists, another process is writing or the database sits on a slow network share. Close other sessions that use the same database and try again.

Suspected database corruption with cloud sync

If db_path lies in Dropbox, OneDrive, Google Drive or iCloud, the database can be silently corrupted. Move it to a local path or a real network share and restore it from a backup or a project export.

The active project changes on its own

The active selection is a single entry in the database. Several Claude sessions or people using the same database overwrite it for each other. Reload the project with /project-hub:resume.

Projects, contacts and notes

"A project with slug ... already exists"

The slug is derived from the name. Choose a different name or continue with the existing project.

A contact is rejected as a duplicate

• "A shared contact with this name or email already exists": a shared contact with the same name or email address exists, even with different spelling. Update the existing contact or use it directly, it is visible in all projects.
• "A shared contact with a very similar name already exists": the name resembles a shared contact. If it is a different person, you confirm that explicitly and the contact is created with force.
• "External contacts cannot be shared": external contacts stay project-specific.

A note change does not show up in the Markdown file

This is expected: changes affect only the database, and the file in the docs folder stays old. The database, reports and search are authoritative. See Technical details.

A field cannot be cleared

Updates write only non-empty values. An empty value leaves the field unchanged, and it can only be overwritten with other text.

Two notes but only one Markdown file

The file name is derived from target folder, date and title slug, not from the note type. Notes with the same title on the same day therefore share a file if they land in the same folder. This also applies to different types: a note and a decision both go to misc/. The title slug is truncated to 50 characters, so different long titles with the same beginning can collide as well. Both notes remain in the database, only the older note's Markdown file is overwritten. Put a date or a distinguishing prefix at the start of the title.

"Kein aktives Projekt" (no active project)

Most skills need a loaded project. Use /project-hub:resume <name> or /project-hub:new-project.

Searching "ärger" does not find "Ärger"

The search ignores case for ASCII letters only. Umlauts must match in their case. In addition, % and _ in a search term act as wildcards.

Attachments

If the .md file next to a PDF or Word document is missing, the conversion failed or was skipped, and the attachment itself is saved regardless.

Knowledge documents

No knowledge documents appear when loading a project

• For projects of type generic, resume does not load knowledge documents. /project-hub:knowledge shows what is installed.
• The files must live under ~/.project-hub/knowledge/<project-type>/ and end in .md. If they are missing, /project-hub:knowledge sync installs the templates.

vacation-handover aborts

No vacation-handover document exists for the project type. Create it with /project-hub:knowledge update vacation-handover. The plugin bundles a template only for merchant-onboarding.

Export and import

• "Unsupported export_version": the file comes from an incompatible plugin version and cannot be imported.
• Import aborts with skip: a project with this slug exists. Choose rename, or overwrite if the existing project should be replaced.
• Caution with overwrite: the import deletes the existing project with its contacts and notes and also removes its entire docs folder from disk. The notes' Markdown files and all attachment files are gone afterwards. Back up the folder first if you still need it.
• Attached files are missing after import: attachment files are not part of the export.

Reports

• The report does not open automatically: the skill always states the file path, open the file in your browser manually.
• Charts are missing: the library is loaded from cdn.jsdelivr.net and needs an internet connection.
• Completed tasks appear under "Offene Aufgaben": the report lists all notes of type action-item without a completion filter.