Skip to content

troubleshooting.md

Latest commit

 

History

History
275 lines (185 loc) · 7.62 KB

troubleshooting.md

File metadata and controls

275 lines (185 loc) · 7.62 KB

Troubleshooting

This guide covers common issues and how to resolve them. Start by running mcs doctor to get a diagnostic report -- most problems will show up there.

mcs doctor           # Diagnose (project + global packs)
mcs doctor --fix     # Diagnose and auto-fix what's possible
mcs doctor --global  # Check globally-configured packs only

Dependencies

Homebrew not installed

Symptom: mcs sync fails with "Homebrew is required but not installed."

Fix: Install Homebrew first:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Then re-run mcs sync.

Xcode Command Line Tools missing

Symptom: mcs sync fails with "Xcode Command Line Tools not found."

Fix:

xcode-select --install

Follow the system dialog to complete installation, then re-run mcs sync.

Node.js not found

Symptom: MCP servers that use npx fail to start or install.

Fix: Node.js is auto-resolved as a dependency if your pack declares it. Re-run:

mcs sync

If you manage Node.js through nvm or similar, make sure it's available in your PATH during installation.

Claude Code CLI not found

Symptom: MCP servers and plugins can't be registered.

Fix: Install Claude Code:

brew install claude-code

Verify:

claude --version

MCP Servers

MCP server not registered

Symptom: mcs doctor shows a server as "not registered" or claude mcp list doesn't show it.

Fix: Re-run sync for your project:

cd /path/to/project
mcs sync

Or for global-scope servers:

mcs sync --global

MCP server registered with wrong scope

Symptom: Server works in one project but not another, or is unexpectedly shared.

MCP servers have three scopes:

  • local (default): per-user, per-project — only active in the project where it was configured
  • project: team-shared — active for anyone who clones the repo
  • user: cross-project — active everywhere

Fix: Remove and re-register with the correct scope:

claude mcp remove <server-name>
cd /path/to/project
mcs sync

Plugins

Plugin not enabled

Symptom: mcs doctor shows a plugin as "not enabled."

Fix: Re-run sync:

mcs sync

You can also manually install a plugin:

claude plugin install <plugin-name>@<org>

Project Configuration

Running mcs sync from ~/.claude or $HOME

Symptom: mcs sync prompts "Did you mean mcs sync --global?" or errors with a message about refusing to sync project scope inside the Claude home directory.

mcs sync without --global treats the current directory as a project. Running it from ~/.claude or $HOME would create ~/.claude/.claude/ and write project-scope tracking state on top of the global Claude install — a silent corruption that mcs doctor could not recognize afterwards. The guard catches the three common forms:

  • Bare interactive (cd ~/.claude && mcs sync) — prompts y/N to promote the run to --global.
  • Non-interactive (mcs sync --pack foo or mcs sync --all) — hard-errors, no prompt.
  • cd ~/.claude && mcs sync --global — silently redirected to $HOME and proceeds (no prompt, no error).

Fix: Either answer y at the prompt, pass --global explicitly, or cd into an actual project directory first:

mcs sync --global              # explicit global sync, works from anywhere
cd ~/Developer/my-project      # or move into the project, then:
mcs sync

The guard is gated on ~/.claude.json existing as a sibling, so it never triggers in test fixtures or fresh installs that haven't run claude yet.

No packs registered

Symptom: mcs sync shows "No packs registered."

Fix: Add a pack first:

mcs pack add https://github.com/user/my-pack
mcs sync

CLAUDE.local.md not found

Symptom: mcs doctor skips project checks or shows "CLAUDE.local.md not found."

Fix: Sync the project:

cd /path/to/your/project
mcs sync

CLAUDE.local.md sections outdated

Symptom: mcs doctor shows "outdated sections."

Fix: Re-run sync to update sections:

cd /path/to/your/project
mcs sync

Managed sections (inside <!-- mcs:begin/end --> markers) are updated. Content you added outside markers is preserved.

.mcs-project file missing

Symptom: mcs doctor warns "CLAUDE.local.md exists but .mcs-project missing."

Fix: mcs doctor --fix can create the state file by inferring packs from CLAUDE.local.md section markers. Or re-run sync:

mcs sync

Per-project artifacts not appearing

Symptom: After mcs sync, expected files are missing from <project>/.claude/.

Causes:

  1. The pack wasn't selected during multi-select
  2. The pack's techpack.yaml doesn't define the expected components

Fix:

# Check what's configured
cat .claude/.mcs-project

# Re-run sync and ensure the pack is selected
mcs sync

Components showing "excluded via --customize"

Symptom: mcs doctor shows dimmed ○ <component>: excluded via --customize entries.

This is informational, not a failure. These components were explicitly deselected during mcs sync --customize and are intentionally skipped. If the component is installed globally, it will show as passing instead.

Unpaired section markers

Symptom: mcs sync warns about "unpaired section markers."

This means a <!-- mcs:begin X --> marker exists without a matching <!-- mcs:end X --> (or vice versa) in CLAUDE.local.md.

Fix: Manually add the missing marker, then re-run sync:

mcs sync

External Packs

Pack add fails

Symptom: mcs pack add fails with a Git error or "path does not exist".

Causes:

  1. The URL/shorthand is not a valid Git repository
  2. No techpack.yaml exists in the repository or directory root
  3. Network connectivity issues (for git packs)
  4. The local path does not exist or is a file instead of a directory

Fix: Verify the source is correct and contains a techpack.yaml:

git ls-remote <url>            # Verify git repo exists
ls /path/to/pack/techpack.yaml # Verify local pack has manifest

Pack update fails

Symptom: mcs pack update fails for a specific pack.

Note: Local packs don't need updating — changes are picked up automatically on next mcs sync.

Fix: For git packs, try removing and re-adding:

mcs pack remove <name>
mcs pack add <url>

Global Gitignore

Missing gitignore entries

Symptom: mcs doctor shows "missing entries" in the gitignore check.

Fix: mcs doctor --fix adds missing entries automatically:

mcs doctor --fix

Backup Files

Too many backup files

Over time, mcs sync creates timestamped backups of files it modifies.

Fix: Clean them up:

mcs cleanup          # Lists backups and asks before deleting
mcs cleanup --force  # Deletes without confirmation

Getting More Help

If mcs doctor doesn't identify the problem:

  1. Check that your PATH includes the necessary binaries (brew, node, claude)
  2. Verify ~/.claude.json is valid JSON: python3 -m json.tool ~/.claude.json
  3. Verify ~/.claude/settings.json is valid JSON: python3 -m json.tool ~/.claude/settings.json
  4. Check .claude/.mcs-project in your project for state corruption
  5. Open an issue at the project repository with the output of mcs doctor

Back to: Documentation Home

Home | CLI Reference | Creating Tech Packs | Schema | Architecture | Troubleshooting