Troubleshooting¶

Solutions to common problems when using Code Scalpel.

Quick Diagnostics¶

Run diagnostics to identify issues:

code-scalpel diagnose

This checks: - Installation integrity - License status - Configuration validity - Connectivity (for MCP)

Installation Issues¶

"command not found: code-scalpel"¶

Cause: Code Scalpel not in PATH.

Solutions:

# Add user bin to PATH
export PATH="$HOME/.local/bin:$PATH"

# Add to shell config
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# Reinstall without --user
pip uninstall codescalpel
sudo pip install codescalpel

# pipx manages PATH automatically
pipx install codescalpel

"ModuleNotFoundError: No module named 'code_scalpel'"¶

Cause: Package not installed in current environment.

Solution:

# Check which Python
which python

# Install in correct environment
python -m pip install codescalpel

# Verify
python -c "import code_scalpel; print(code_scalpel.__version__)"

Docker permission denied¶

Cause: User not in docker group.

Solution:

sudo usermod -aG docker $USER
newgrp docker

MCP Connection Issues¶

"MCP server not found"¶

Cause: Server not running or misconfigured.

Check 1: Is the server running?

# Start server manually
code-scalpel serve

# Should show:
# Starting MCP server on stdio...

Check 2: Is the config correct?

// ~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "code-scalpel": {
      "command": "code-scalpel",
      "args": ["serve"]
    }
  }
}

"Connection refused" or timeout¶

Cause: Port conflict or firewall.

Solutions:

1. Check if another process uses the port:

   lsof -i :8080
   

2. Try a different port:

   code-scalpel serve --port 8081
   

3. Check firewall rules

"Invalid MCP message"¶

Cause: Version mismatch or corrupted data.

Solution:

# Update Code Scalpel
pip install --upgrade code-scalpel

# Restart your AI assistant

Analysis Errors¶

"Symbol not found: xyz"¶

Cause: The symbol name doesn't exist in the file.

Solution 1: Check spelling

Code Scalpel suggests corrections:

{
  "error": {
    "code": "SYMBOL_NOT_FOUND",
    "symbol": "calculte",
    "suggestions": ["calculate", "calculate_total"]
  }
}

Solution 2: Analyze first

{
  "tool": "analyze_code",
  "parameters": {"file_path": "module.py"}
}

This shows all available symbols.

Solution 3: Check scope

Methods require class prefix:

// Wrong
{"target_name": "process"}

// Correct
{"target_name": "MyClass.process"}

"File not found: xyz.py"¶

Cause: Path is incorrect or file doesn't exist.

Solution:

{
  "tool": "validate_paths",
  "parameters": {
    "paths": ["xyz.py"]
  }
}

Returns suggestions for similar files.

"Syntax error in file"¶

Cause: The file has invalid Python/JS/TS syntax.

Solution:

1. Fix the syntax error in the source file
2. Or specify language explicitly:

   {"language": "python"}
   

"Analysis timeout"¶

Cause: File or project too large.

Solutions:

1. Reduce scope:

   {"file_path": "specific_file.py"}  // Not entire directory
   

2. Add exclude patterns:

   // config.json
   {
     "analysis": {
       "exclude_patterns": ["**/node_modules/**", "**/__pycache__/**"]
     }
   }
   

3. Increase timeout (Pro+):

   # limits.toml
   [pro.cross_file_security_scan]
   timeout_seconds = 300
   

Security Scan Issues¶

"No vulnerabilities found" (false negative?)¶

Cause: Confidence threshold too high or taint source not recognized.

Solutions:

1. Lower confidence threshold:

   {"confidence_threshold": 0.5}
   

2. Add custom taint sources:

   // config.json
   {
     "security": {
       "taint_sources": ["my_custom_input_function"]
     }
   }
   

"Too many false positives"¶

Cause: Confidence threshold too low or sanitizers not recognized.

Solutions:

1. Raise confidence threshold:

   {"confidence_threshold": 0.8}
   

2. Add custom sanitizers:

   // config.json
   {
     "security": {
       "custom_sanitizers": ["my_escape_function", "my_validate_function"]
     }
   }
   

Cross-file scan misses vulnerabilities¶

Cause: Taint flow too deep or modules not discovered.

Solutions:

1. Increase depth:

   {"max_depth": 10}
   

2. Specify entry points:

   {"entry_points": ["routes/api.py:handle_request"]}
   

License Issues¶

"License not found"¶

Check 1: Environment variable

echo $CODE_SCALPEL_LICENSE_PATH
# Should show path to your license.jwt

Check 2: File exists

ls -la /path/to/license.jwt
# Should show the file

Check 3: Correct path

export CODE_SCALPEL_LICENSE_PATH=/absolute/path/to/license.jwt

"License expired"¶

Contact sales for renewal:

Renew License

"License invalid"¶

Cause: Corrupted file or wrong license.

Solution:

1. Re-download the license file
2. Verify the download:

   code-scalpel license verify
   

"Feature not available in your tier"¶

Cause: Trying to use Pro/Enterprise feature on Community.

Solution:

1. Check current tier:

   code-scalpel license info
   

2. Upgrade if needed

3. Or use a Community-tier alternative

Performance Issues¶

Analysis is slow¶

Diagnosis:

time code-scalpel analyze ./src

Solutions:

1. Exclude unnecessary files:

   {
     "analysis": {
       "exclude_patterns": [
         "**/test_*.py",
         "**/*_test.py",
         "**/migrations/**"
       ]
     }
   }
   

2. Enable caching:

   # governance.yaml
   analysis:
     enable_cache: true
     cache_ttl_minutes: 60
   

3. Reduce limits:

   # limits.toml
   [pro.get_call_graph]
   max_depth = 20  # Reduce from 50
   max_nodes = 200  # Reduce from 500
   

Memory issues¶

Cause: Large codebase or deep analysis.

Solutions:

1. Docker memory limit:

   docker run -m 4g ghcr.io/codescalpel/code-scalpel ...
   

2. Reduce concurrent analysis: Analyze one directory at a time

Docker Issues¶

"Cannot mount volume"¶

Cause: Permission or path issues.

Solutions:

# Use absolute paths
docker run -v $(pwd):/workspace ghcr.io/codescalpel/code-scalpel

# Check SELinux (Linux)
docker run -v $(pwd):/workspace:Z ghcr.io/codescalpel/code-scalpel

Container exits immediately¶

Cause: Missing command or error.

Solution:

# Check logs
docker logs <container_id>

# Run interactively
docker run -it ghcr.io/codescalpel/code-scalpel bash

Getting Help¶

If these solutions don't help:

1. Search existing issues: GitHub Issues

2. Ask the community: GitHub Discussions

3. Report a bug: Include:

4. Code Scalpel version (code-scalpel --version)
5. Platform and OS
6. Error message (full)
7. Steps to reproduce

Report Bug