Skip to content

troubleshooting.md

Latest commit

 

History

History
222 lines (147 loc) · 6.21 KB

troubleshooting.md

File metadata and controls

222 lines (147 loc) · 6.21 KB

Troubleshooting

Common issues and how to fix them.

Server Won't Start

"Unable to determine server root"

Cause: Working directory isn't server/ or paths aren't absolute.

Fix:

  1. Run from server/ directory
  2. Use --workspace flag or MCP_WORKSPACE environment variable to set your workspace
  3. Run with --debug-startup to see detection strategies: 
    node dist/index.js --transport=stdio --debug-startup

Recommended: Use the new path configuration system instead of deprecated env vars:

# Via CLI flags
npx claude-prompts --workspace=/path/to/workspace

# Via environment variables
MCP_WORKSPACE=/path/to/workspace npx claude-prompts

Config JSON Syntax Error

Cause: Invalid JSON in config.json blocks startup.

Fix:

node -e "JSON.parse(require('fs').readFileSync('config.json'))"

Note

For all CLI flags and environment variables, see the CLI Configuration section in the MCP Tools reference.

MCP Client Issues

Client Won't Connect

Cause: STDIO conflict, wrong paths, or JSON syntax error in client config.

Fix:

  1. Run server manually to verify startup: 
    node dist/index.js --transport=stdio --verbose
  2. Check Claude Desktop logs:
    • macOS: ~/Library/Logs/Claude/
    • Windows: %APPDATA%\Claude\logs
  3. Ensure absolute paths in claude_desktop_config.json

Tools Not Appearing in Client

Cause: Server didn't register tools or client cache is stale.

Fix:

  1. Check system_control(action: "status") to verify server is running
  2. Restart Claude Desktop to refresh MCP connections
  3. Verify prompts.registerWithMcp: true in config.json

Note

For per-client setup instructions, see the Client Integration Guide or the Quick Start in the README.

Prompt Issues

Prompts Not Loading

Cause: Prompt not listed in registry or file path mismatch.

Fix:

  1. Check registry: resource_manager(resource_type: "prompt", action: "list")
  2. Verify path in prompts/promptsConfig.json
  3. Manual reload: resource_manager(resource_type: "prompt", action: "reload")

Hot Reload Not Working

Cause: File watcher issue or file not in watched paths.

Fix:

  1. Confirm file is listed in prompts/promptsConfig.json
  2. Trigger manual reload: resource_manager(resource_type: "prompt", action: "reload")
  3. Check server/logs/ for watcher errors
  4. Use supervisor mode if STDIO sessions must persist during reload

Note

For prompt creation and file structure, see the Build Your First Prompt tutorial. For the full schema, see Prompt YAML Schema.

Chain Issues

Chain Sessions Reset Unexpectedly

Cause: runtime-state/state.db permissions or corruption.

Fix:

  1. Check write permissions on runtime-state/ directory
  2. Delete state.db and restart (sessions will reset)
  3. In CI, use HTTP transport (--transport=streamable-http) to avoid STDIO restrictions

Note

For chain concepts and session management, see Chains Lifecycle. For chain step configuration, see Chain Schema Reference.

Chain Stuck / Won't Advance

Cause: Gate failed and waiting for verdict, or session corrupted.

Fix:

  1. Check if gate review is pending—send gate_verdict (preferred format: GATE_REVIEW: PASS/FAIL - reason) or gate_action when retries are exhausted
  2. Bundle responses for efficiency: include both user_response and gate_verdict in one call
  3. Force restart: prompt_engine(command: ">>prompt", force_restart: true)
  4. Inspect session: system_control(action: "status")

Framework Issues

"No active framework" Messages

Expected behavior when you haven't switched methodologies.

Fix (if you want a framework active):

system_control(action: "framework", operation: "switch", framework: "CAGEERF")

Framework Not Injecting into Prompts

Cause: Injection disabled in config or using %clean modifier.

Fix:

  1. Check methodologies.enabled: true in config.json
  2. Remove %clean or %lean modifiers from command
  3. Use %guided to force injection

Note

For injection frequency tuning and modifier details, see the Injection Control Guide.

Gate Issues

Gates Not Appearing in Output

Cause: No gates specified or framework gates disabled.

Fix:

  1. Add gates explicitly: gates: ["code-quality"] or :: 'criteria'
  2. Check gates.methodologyGates: true in config
  3. Verify gate activation rules match your prompt category

Gate Keeps Failing

Cause: Retry limit reached or criteria unclear.

Fix:

  1. Use gate_action: "skip" to bypass and continue
  2. Use gate_action: "retry" to reset attempt counter
  3. Clarify criteria in the gate definition

Note

For gate syntax, types, and best practices, see the Gates Guide. For the full gate.yaml schema, see Gate Configuration Reference.

Logging & Diagnostics

Enable Verbose Logging

node dist/index.js --transport=stdio --verbose

Or set environment variable:

LOG_LEVEL=debug node dist/index.js --transport=stdio

Log File Locations

  • Server logs: server/logs/*.log
  • Claude Desktop: ~/Library/Logs/Claude/ (macOS) or %APPDATA%\Claude\logs (Windows)

Get Runtime Status

system_control(action: "status")

Returns: framework state, transport type, prompt count, gate metrics.

Filing Issues

When reporting bugs, include:

  1. Output of system_control(action: "status")
  2. Relevant logs from server/logs/*.log
  3. Prompt IDs and chain_ids involved
  4. Transport type (STDIO/SSE/Streamable HTTP)
  5. Node.js version: node -v
  6. Steps to reproduce

See Also