# Troubleshooting Guide
## Common Installation Issues
### "Python not found" or "Command not found"
**Problem**: Python not in system PATH
**Solution**: Use absolute paths or add Python to PATH
```bash
# Find your Python path
which python # Mac/Linux
where python # Windows
# Test if Python is accessible
python --version
```
**Config options**:
```json
// Use absolute Python path (recommended)
{"command": "/usr/bin/python3", "args": ["-m", "src.server"], "env": {}}
// Windows example
{"command": "C:\\Python313\\python.exe", "args": ["-m", "src.server"], "env": {}}
```
### "Module not found" errors
**Problem**: Package not installed system-wide
**Solution**: Install with pip
```bash
# System-wide install
pip install -e .
# Or with user permissions ( no sudo needed )
pip install --user -e .
```
### "Permission denied" on Windows
**Problem**: PowerShell execution policy
**Solution**: Run as administrator or change policy
```powershell
# Temporarily allow scripts
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
# Or run the server directly
.venv\Scripts\python.exe -m src.server
```
### MCP server not loading in IDE
**Problem**: Configuration errors or path issues
**Solution**: Test the command first
```bash
# Test the exact command from your config
/full/path/to/.venv/bin/python -m src.server
# Should output: "MCP server running on stdio..."
```
### Scanning too many files (including .venv)
**Problem**: Scanner not ignoring virtual environments
**Solution**: Verify ignore patterns are working
The scanner automatically ignores:
- `.venv/`, `.env/`, `venv/`
- `node_modules/`, `__pycache__/`
- `.git/`, `.pytest_cache/`
If still scanning too much, check:
```bash
# Test with a small directory
python -c "from src.server import scan_directory; import json; print(json.loads(scan_directory('.'))['stats']['files_scanned'])"
```
## IDE Specific Issues
### Windsurf/Kiro
1. **Config location**: `~/.codeium/windsurf/mcp_config.json`
2. **No `cwd` support**: Use absolute paths in `command`
3. **Restart required**: After config changes, restart IDE
### Claude Desktop
1. **Config location**: `~/Library/Application Support/Claude/claude_desktop_config.json` (Mac)
2. **Supports `cwd`**: Can set working directory
3. **Log location**: Check Claude logs for MCP errors
## CLI Issues
### "ModuleNotFoundError: No module named 'src'"
**Problem**: Running CLI from wrong directory
**Solution**: Run from project root directory
```bash
# Must be in credential-free directory
cd /path/to/credential-free
python -m src info
```
### "Invalid exclude pattern" errors
**Problem**: Regex syntax errors in exclude patterns
**Solution**: Use proper regex escaping
```bash
# Correct usage
python -m src scan directory . --exclude-patterns '.*\.txt$' '.*\.md$'
# Avoid unescaped backslashes
# Wrong: '.*\.txt\' # Right: '.*\.txt$'
```
## Quick Test Commands
### MCP Server Tests
```bash
# Test server loads
python -c "from src.server import mcp; print('✅ Server loads')"
# Test patterns
python -c "from src.server import get_patterns; import json; p=json.loads(get_patterns()); print('✅ {} patterns'.format(p['count']))"
# Test scanning
python -c "from src.server import scan_content; import json; r=json.loads(scan_content('AKIAIOSFODNN7EXAMPLE', 'test.py')); print('✅ Found {} secrets'.format(r['count']))"
```
### CLI Tests
```bash
# Test CLI info
python -m src info
# Test CLI scan
python -m src scan file README.md
# Test CLI with exclusions
python -m src scan directory . --exclude-patterns '.*\.txt$'
```
## Performance Tips
- Exclude large directories: `node_modules/`, `dist/`, `build/`
- Use "fast" profile for quick scans: `scan_directory(".", profile="fast")`
- Avoid scanning binary files and archives
## Getting Help
1. Check the exact error message in your IDE's MCP logs
2. Test commands manually in terminal
3. Verify Python paths with `which python` or `where python`
4. Ensure all dependencies are installed system-wide
