Troubleshooting

Solutions to common problems when using Code Scalpel.

Quick Diagnostics

Run diagnostics to identify issues:

code-scalpel diagnose

Installation Issues

"command not found: code-scalpel"

Cause: Code Scalpel not in PATH.

Solution (pip user install):

export PATH="$HOME/.local/bin:$PATH"

"ModuleNotFoundError: No module named 'code_scalpel'"

Solution: Install in the correct environment.

python -m pip install codescalpel

MCP Connection Issues

"MCP server not found"

Check if the server is running manually:

code-scalpel serve

"Connection refused"

Check for port conflicts or try a different port:

code-scalpel serve --port 8081

Analysis Errors

"Symbol not found: xyz"

Check spelling or use analyze_code to find the correct symbol name.

"File not found: xyz.py"

Use validate_paths to check file existence.

"Analysis timeout"

Reduce scope, add exclude patterns, or increase timeout limits.

License Issues

"License not found"

Ensure CODE_SCALPEL_LICENSE_PATH is set correctly.

echo $CODE_SCALPEL_LICENSE_PATH