Skip to content

troubleshooting.md

Latest commit

 

History

History
312 lines (214 loc) · 9.85 KB

troubleshooting.md

File metadata and controls

312 lines (214 loc) · 9.85 KB
Raw

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, then repair after one confirmation (re-syncs scopes with missing artifacts)
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: mcs installs Node.js only when a pack declares it as a component (brew: node). Add one to the pack that needs it, then 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 fails with "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

A hook is registered but never runs

Symptom: mcs doctor passes, the hook file exists, the settings entry is there — and nothing happens. Hook logs are empty, which reads as "no problems" rather than "never ran".

Causes:

  1. The interpreter is not on Claude Code's PATH. This is the common one. Claude Code runs hooks through a shell that may not have /opt/homebrew/bin or a version manager's shims (nvm, mise, pyenv, rbenv, volta). node in your terminal is not proof node resolves for the hook.
  2. The interpreter is missing entirely. Check the Hooks section of mcs doctor, which verifies each pack's interpreter binary.
  3. The interpreter is wrong for the file. A .ts hook with no hookInterpreter runs under bash, which cannot parse it. mcs pack validate warns the pack author about this.
  4. The flags are unsupported by the installed version — for example node --experimental-strip-types needs Node 22.6 or newer. The derived doctor check verifies the binary, not its flags.

Fix:

# What command is actually registered?
python3 -m json.tool .claude/settings.local.json | grep -A2 '"command"'

# Does the interpreter resolve, and from where?
which node

# Run the registered command by hand from the project root
bash -c 'node --version'

If which points inside ~/.nvm, ~/.pyenv, ~/.asdf, ~/.rbenv or similar, mcs doctor reports it as a warning. Install the runtime somewhere always on PATH (brew install node), or ask the pack author for a .sh wrapper that sources the version manager before invoking the real interpreter.

Components you excluded are installed after upgrading

Symptom: mcs sync or mcs update prints "Previously excluded components of will now be installed", or mcs doctor fails checks for components you had deselected.

mcs sync --customize has been removed: a pack now always installs every component it declares. The first sync after upgrading installs the components an earlier --customize left out and forgets the old exclusion. Until that sync runs, mcs doctor reports those components as missing — mcs doctor --fix runs the same re-sync. If you need a pack without some of its components, fork it or write your own pack.

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
mcs cleanup --all-projects  # Also scans every project tracked in the index

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. Verify your project's .claude/settings.local.json is valid JSON — doctor reports it as unreadable when it can't be parsed, and checks then fall back to the global file
  5. Check .claude/.mcs-project in your project for state corruption
  6. 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