Skip to main content

Troubleshooting

Solutions to common issues with SCM.

Installation Issues​

Command Not Found​

Problem: scm: command not found

Solutions:

  1. Ensure Go bin is in PATH:
export PATH=$PATH:$(go env GOPATH)/bin
  1. Reinstall:
go install github.com/SophisticatedContextManager/scm@latest
  1. Verify installation:
which scm
scm --version

Build Errors​

Problem: Build fails with dependency errors

Solution:

go clean -modcache
go mod download
go install github.com/SophisticatedContextManager/scm@latest

Context Not Injected​

Hooks Not Applied​

Problem: Context doesn't appear in Claude Code sessions

Check hooks configuration:

cat .claude/settings.json | jq '.hooks'

Expected output:

{
  "SessionStart": {
    "hooks": [
      {
        "type": "command",
        "command": "scm hook inject-context <hash>"
      }
    ]
  }
}

Fix:

scm hooks apply

Context File Missing​

Problem: Hook runs but no context appears

Check context file:

ls -la .scm/context/

Regenerate:

scm hooks apply --regenerate

Wrong Directory​

Problem: SCM not finding configuration

Check you're in the right directory:

# Should show your .scm directory
ls -la .scm/

# Or initialize if missing
scm init

Remote Issues​

Authentication Failed​

Problem: 401 Unauthorized or 403 Forbidden when accessing remotes

Solution - Set authentication token:

# GitHub
export GITHUB_TOKEN=ghp_xxxxxxxxxxxx

# GitLab
export GITLAB_TOKEN=glpat-xxxxxxxxxxxx

Verify token:

# Test GitHub access
curl -H "Authorization: token $GITHUB_TOKEN" https://api.github.com/user

Rate Limiting​

Problem: 403 rate limit exceeded

Solutions:

  1. Set authentication token (increases rate limit):
export GITHUB_TOKEN=ghp_xxxxxxxxxxxx

  1. Wait for rate limit reset (usually 1 hour)

  2. Check current rate limit:

curl -H "Authorization: token $GITHUB_TOKEN" \
  https://api.github.com/rate_limit

Remote Not Found​

Problem: remote not found: myremote

Check configured remotes:

scm remote list

Add the remote:

scm remote add myremote owner/repo

Sync Failures​

Problem: scm remote sync fails

Debug:

# Check what's being synced
scm remote sync --dry-run

# Sync with verbose output
SCM_VERBOSE=1 scm remote sync

# Force re-sync
scm remote sync --force

Profile Issues​

Profile Not Found​

Problem: profile not found: myprofile

List available profiles:

scm profile list

Check profile location:

ls .scm/profiles/
ls ~/.scm/profiles/

Circular Inheritance​

Problem: circular profile inheritance detected

Check profile parents:

scm profile show myprofile

Fix: Remove circular parent references in profile YAML.

Missing Bundles​

Problem: Profile references bundles that don't exist

Check what bundles are available:

scm fragment list

Install missing bundles:

scm fragment install remote/missing-bundle

Fragment Issues​

Fragment Not Found​

Problem: fragment not found: myfrag

List available fragments:

scm fragment list
scm fragment list --bundle mybundle

Check fragment reference format:

# Correct formats:
scm fragment show mybundle#fragments/fragname
scm fragment show fragname  # searches all bundles

YAML Parse Error​

Problem: failed to parse bundle: yaml error

Validate YAML syntax:

# Check for syntax errors
scm validate .scm/bundles/mybundle.yaml

# Or use a YAML linter
yamllint .scm/bundles/mybundle.yaml

Common YAML issues:

  • Incorrect indentation (use spaces, not tabs)
  • Missing quotes around special characters
  • Improper multiline string syntax

Content Too Large​

Problem: warning: assembled context is 24KB (recommended max: 16KB)

Solutions:

  1. Distill verbose fragments:
scm fragment distill mybundle
  1. Use fewer fragments:
# Check what's included
scm run --dry-run --print | wc -c
  1. Create focused profiles:
# Instead of one large profile, create task-specific ones
# api-dev.yaml - only API-related fragments
# testing.yaml - only testing fragments

MCP Server Issues​

Server Won't Start​

Problem: scm mcp serve fails

Check for port conflicts:

# MCP uses stdio, but check for other issues
scm mcp serve 2>&1 | head -20

Verbose mode:

SCM_VERBOSE=1 scm mcp serve

Tools Not Appearing​

Problem: MCP tools don't show up in Claude Code

Check MCP configuration:

cat .claude/settings.json | jq '.mcpServers'

Ensure SCM is registered:

scm mcp auto-register --enable
scm hooks apply

Restart Claude Code after configuration changes.

Tool Execution Fails​

Problem: MCP tool returns error

Check SCM logs:

# Run MCP server with verbose logging
SCM_VERBOSE=1 scm mcp serve

Test tool directly:

# Test the underlying CLI command
scm fragment list
scm profile list

Performance Issues​

Slow Context Assembly​

Problem: scm run takes a long time

Diagnose:

time scm run --dry-run

Solutions:

  1. Reduce fragment count - use fewer, more focused fragments
  2. Use distillation - smaller fragments load faster
  3. Check disk I/O - ensure .scm/ isn't on slow storage

Slow Remote Operations​

Problem: Remote sync/browse is slow

Solutions:

  1. Check network - ensure good connectivity to GitHub/GitLab
  2. Use caching - SCM caches remote content locally
  3. Reduce scope - sync specific profiles instead of all:
scm remote sync --profiles myprofile

Configuration Issues​

Config Not Loading​

Problem: Configuration changes not taking effect

Check config location:

# Project config
cat .scm/config.yaml

# User config
cat ~/.scm/config.yaml

Validate config:

scm validate .scm/config.yaml

Environment Variables Not Working​

Problem: Environment variables aren't being used

Check variable is set:

echo $MY_VARIABLE

Check variable syntax in templates:

# Correct
content: "API key: {{API_KEY}}"

# Wrong
content: "API key: $API_KEY"

Getting Help​

Debug Mode​

Enable verbose output for any command:

SCM_VERBOSE=1 scm <command>

Check Version​

Ensure you're on the latest version:

scm --version

# Update
go install github.com/SophisticatedContextManager/scm@latest

Report Issues​

If you've tried the above and still have issues:

  1. Gather information:
scm --version
go version
uname -a

  1. Create minimal reproduction

  2. File issue: https://github.com/SophisticatedContextManager/scm/issues

Include:

  • SCM version
  • Operating system
  • Steps to reproduce
  • Expected vs actual behavior
  • Relevant configuration (sanitized)