CodeGuard Troubleshooting Guide

This guide helps you diagnose and resolve common issues with CodeGuard.

Extension Not Activating
Analysis Issues
Performance Problems
AI Features Not Working
Cache Issues
Configuration Problems
Memory Issues
False Positives
Diagnostic Tools
Getting Help

Extension Not Activating

Symptom

CodeGuard doesn't appear to be running. No diagnostics appear, status bar is missing.

Possible Causes & Solutions

1. Extension Not Installed

Check: Extensions view (Ctrl+Shift+X)

Solution: Install CodeGuard from the marketplace

2. Extension Disabled

Check: Extensions view → CodeGuard → Enabled

Solution: Click "Enable" button

3. Unsupported File Type

Check: File extension and language mode

Supported: .js, .ts, .py, .java
Solution: Open a supported file type

4. Extension Crashed

Check: Output panel (View → Output → CodeGuard)

Solution: 
1. Check for error messages
2. Reload window: Ctrl+Shift+P → "Developer: Reload Window"
3. If persists, reinstall extension

5. Activation Event Not Triggered

Check: package.json activation events

Solution:
1. Open a supported file (.js, .ts, .py, .java)
2. Or manually trigger: Ctrl+Shift+P → "CodeGuard: Analyze Current File"

Verification Steps

Check extension is installed:
- Open Extensions view (Ctrl+Shift+X)
- Search for "CodeGuard"
- Verify it shows "Installed"
Check extension is enabled:
- In Extensions view, ensure CodeGuard is not disabled
- Check both workspace and globally
Check Output panel:
- View → Output
- Select "CodeGuard" from dropdown
- Look for activation messages or errors
Check file language:
- Bottom-right corner of VSCode shows language mode
- Should be JavaScript, TypeScript, Python, or Java

Analysis Issues

Symptom

Analysis doesn't run or diagnostics don't appear.

Issue: Analysis Not Triggering

Possible Causes:

CodeGuard disabled in settings
Debounce delay too long
File too large (timeout)
Analyzer crashed

Solutions:

// Check settings
{
  "codeguard.enabled": true,  // Must be true
  "codeguard.debounceMs": 500  // Try reducing if too slow
}

Manual trigger:

Ctrl+Shift+P → "CodeGuard: Analyze Current File"
Or keyboard shortcut: Ctrl+Shift+G

Issue: Diagnostics Not Appearing

Check:

Problems panel (Ctrl+Shift+M) - are issues listed?
Output panel - any error messages?
Specific analyzers enabled?

Solutions:

// Ensure analyzers are enabled
{
  "codeguard.analyzers.security.enabled": true,
  "codeguard.analyzers.performance.enabled": true,
  "codeguard.analyzers.secrets.enabled": true,
  "codeguard.analyzers.codeSmells.enabled": true
}

Issue: Analysis Timeout

Symptom: Large files don't complete analysis

Solution:

{
  "codeguard.maxAnalysisTimeMs": 10000  // Increase timeout
}

Or enable incremental analysis (automatic for files >5000 lines).

Issue: Specific Analyzer Not Working

Check which analyzers ran:

Output panel shows which analyzers executed
Check for analyzer-specific errors

Solution:

// Disable problematic analyzer temporarily
{
  "codeguard.analyzers.security.enabled": false
}

Then report the issue on GitHub with:

File content (if shareable)
Error messages from Output panel
CodeGuard version

Performance Problems

Symptom

Analysis is slow, VSCode feels sluggish, high CPU/memory usage.

Issue: Slow Analysis

Causes:

Large files
Cache disabled
Too many analyzers enabled
Debounce too short

Solutions:

{
  // Increase debounce to reduce frequency
  "codeguard.debounceMs": 1000,
  
  // Enable caching
  "codeguard.cache.enabled": true,
  
  // Disable unused analyzers
  "codeguard.analyzers.codeSmells.enabled": false
}

For large files:

Incremental analysis activates automatically at 5000 lines
Consider splitting large files

Issue: High CPU Usage

Check:

Task Manager / Activity Monitor
VSCode's "Show Running Extensions"

Solutions:

Increase debounce:
```
{
  "codeguard.debounceMs": 1000
}
```

Disable analyzers:

{
  "codeguard.analyzers.performance.enabled": false
}

Limit analysis scope:
- Close unused files
- Use .codeguardignore to exclude files

Issue: High Memory Usage

Check: Task Manager / Activity Monitor

Solutions:

{
  // Reduce cache size
  "codeguard.cache.maxMemoryMB": 25,
  "codeguard.cache.maxDiskMB": 250,
  
  // Or disable caching
  "codeguard.cache.enabled": false
}

If memory usage exceeds 200MB:

CodeGuard automatically disables caching
Check Output panel for warnings
Consider restarting VSCode

Issue: VSCode Freezing

Cause: Analysis blocking main thread (bug)

Immediate solution:

Disable CodeGuard temporarily
Reload window
Report bug on GitHub

Workaround:

{
  "codeguard.enabled": false
}

AI Features Not Working

Symptom

"Fix with AI" doesn't work or produces errors.

Issue: AI Not Enabled

Check:

{
  "codeguard.ai.enabled": true,  // Must be true
  "codeguard.ai.provider": "ollama"  // Must not be "none"
}

Issue: Ollama Not Running

For local AI (Ollama):

Check Ollama is installed:
```
ollama --version
```
Check Ollama is running:
```
ollama list
```
Pull a model:
```
ollama pull codellama
```

Configure CodeGuard:

{
  "codeguard.ai.enabled": true,
  "codeguard.ai.provider": "ollama",
  "codeguard.ai.model": "codellama"
}

Issue: OpenAI/Claude API Errors

Check API key:

{
  "codeguard.ai.apiKey": "sk-..."  // Must be valid
}

Common errors:

Invalid API key:
- Verify key at https://platform.openai.com/api-keys
- Ensure key has correct permissions
Rate limit exceeded:
- Wait for rate limit to reset
- CodeGuard automatically retries with backoff
Network error:
- Check internet connection
- Check firewall settings
- Try different network

Model not available:

{
  "codeguard.ai.model": "gpt-4"  // Verify model exists
}

Issue: AI Timeout

Symptom: "Fix with AI" times out

Solution:

{
  "codeguard.ai.timeout": 5000  // Increase timeout (ms)
}

Issue: Poor AI Suggestions

Causes:

Model not suitable for code
Insufficient context
Complex issue

Solutions:

Try different model:

{
  "codeguard.ai.model": "gpt-4"  // More capable
}

Adjust temperature:

{
  "codeguard.ai.temperature": 0.1  // More deterministic
}

Use rule-based fixes:
- Disable AI temporarily
- CodeGuard falls back to rule-based fixes

Cache Issues

Symptom

Cache not working, stale results, or cache errors.

Issue: Cache Not Working

Check:

{
  "codeguard.cache.enabled": true  // Must be true
}

Verify cache is working:

Output panel shows "cache hit" messages
Second analysis of same file should be instant

Issue: Stale Results

Symptom: Old diagnostics persist after fixing code

Solution:

Clear cache:
- Ctrl+Shift+P → "CodeGuard: Clear Cache"
Reload window:
- Ctrl+Shift+P → "Developer: Reload Window"
Disable cache temporarily:
```
{
  "codeguard.cache.enabled": false
}
```

Issue: Cache Corruption

Symptom: Errors about cache, inconsistent results

Solution:

Delete cache directory:
- Windows: %APPDATA%\Code\User\globalStorage\codeguard\cache
- Mac: ~/Library/Application Support/Code/User/globalStorage/codeguard/cache
- Linux: ~/.config/Code/User/globalStorage/codeguard/cache
Reload VSCode

Issue: Cache Taking Too Much Space

Check disk usage:

Default: 500MB max
Location: See above

Solution:

{
  "codeguard.cache.maxDiskMB": 250  // Reduce limit
}

Or clear cache periodically:

Ctrl+Shift+P → "CodeGuard: Clear Cache"

Configuration Problems

Symptom

Settings not taking effect, configuration errors.

Issue: Settings Not Applied

Check configuration priority:

.codeguardrc.json (highest priority)
Workspace settings
User settings
Default settings

Solution:

Check all configuration sources
Remove conflicting settings
Reload window after changes

Issue: Invalid Configuration

Symptom: Error messages about configuration

Check:

JSON syntax in .codeguardrc.json
Valid values for enum settings
Correct types (number vs string)

Example valid configuration:

{
  "version": "1.0",
  "enabled": true,
  "debounceMs": 500,
  "analyzers": {
    "security": {
      "enabled": true,
      "severity": {
        "sql-injection": "error"
      }
    }
  }
}

Issue: Configuration Not Found

Symptom: .codeguardrc.json ignored

Check:

File is in workspace root
File name is exactly .codeguardrc.json
JSON is valid (use JSON validator)

Verify:

# In workspace root
ls -la .codeguardrc.json

Memory Issues

Symptom

High memory usage, out of memory errors.

Issue: Memory Leak

Symptoms:

Memory usage grows over time
VSCode becomes slow
Eventually crashes

Immediate solution:

Reload window: Ctrl+Shift+P → "Developer: Reload Window"
Reduce cache size (see above)

Report bug:

Include memory profile
Steps to reproduce
VSCode version and OS

Issue: Memory Limit Exceeded

Symptom: Warning about memory usage >200MB

Solutions:

{
  // Reduce cache
  "codeguard.cache.maxMemoryMB": 25,
  
  // Or disable cache
  "codeguard.cache.enabled": false,
  
  // Disable unused analyzers
  "codeguard.analyzers.codeSmells.enabled": false
}

False Positives

Symptom

CodeGuard flags code that is actually safe.

Issue: Too Many False Positives

Solutions:

Ignore specific issue:
- Hover over diagnostic
- Click "Ignore this issue"
- Adds to .codeguardignore

Adjust severity:

{
  "analyzers": {
    "security": {
      "severity": {
        "sql-injection": "warning"  // Downgrade from error
      }
    }
  }
}

Disable specific rule:

{
  "analyzers": {
    "security": {
      "customRules": {
        "sql-injection": false
      }
    }
  }
}

Report false positive:
- Open issue on GitHub
- Include code sample
- Explain why it's a false positive

Issue: Ignoring Not Working

Check .codeguardignore file:

{
  "version": "1.0",
  "rules": [
    {
      "ruleId": "sql-injection",
      "filePattern": "src/legacy/**",
      "reason": "Legacy code"
    }
  ]
}

Verify:

File is in workspace root
JSON is valid
Rule ID matches diagnostic code
File pattern matches file path

Diagnostic Tools

Enable Debug Logging

{
  "codeguard.logLevel": "debug"
}

Then check Output panel (View → Output → CodeGuard).

Check Extension Status

Running Extensions:
- Ctrl+Shift+P → "Developer: Show Running Extensions"
- Find CodeGuard
- Check activation time and status
Extension Host Log:
- Help → Toggle Developer Tools
- Console tab
- Filter for "CodeGuard"

Profile Performance

Profile Extension:
- Developer: Show Running Extensions
- Click "Profile" next to CodeGuard
- Perform actions
- Stop profiling
- Analyze results
CPU Profile:
- Help → Toggle Developer Tools
- Performance tab
- Record profile
- Analyze hot paths

Memory Profiling

Heap Snapshot:
- Help → Toggle Developer Tools
- Memory tab
- Take heap snapshot
- Analyze memory usage
Memory Timeline:
- Memory tab
- Record allocation timeline
- Identify memory leaks

Network Monitoring

Check AI API calls:

Help → Toggle Developer Tools
Network tab
Filter for API domains
Verify requests/responses

Getting Help

Before Asking for Help

Collect this information:

CodeGuard version:
- Extensions view → CodeGuard → Version
VSCode version:
- Help → About
Operating system:
- Windows, Mac, Linux + version
Error messages:
- Output panel (View → Output → CodeGuard)
- Developer Tools console
Configuration:
- Settings (sanitize API keys!)
- .codeguardrc.json content
Steps to reproduce:
- Detailed steps
- Sample code (if shareable)

Where to Get Help

Documentation:
- README.md
- CONTRIBUTING.md
- GitHub Wiki
GitHub Issues:
- Search existing issues
- Open new issue with template
GitHub Discussions:
- Ask questions
- Share ideas
- Get community help
Discord:
- Real-time chat
- Community support
GitHub Support:
- https://github.com/lekhanpro/CodeGuard/issues
- For all support requests

Reporting Bugs

Use the bug report template:

**Describe the bug**
A clear description of what the bug is.

**To Reproduce**
Steps to reproduce:
1. Open file '...'
2. Type '...'
3. See error

**Expected behavior**
What you expected to happen.

**Actual behavior**
What actually happened.

**Screenshots**
If applicable, add screenshots.

**Environment**
- CodeGuard version: [e.g., 0.1.0]
- VSCode version: [e.g., 1.85.0]
- OS: [e.g., Windows 11]

**Logs**
Paste relevant logs from Output panel.

**Configuration**
Paste relevant settings (sanitize secrets!).

Emergency Workarounds

If CodeGuard is completely broken:

Disable extension:
- Extensions view → CodeGuard → Disable
Uninstall and reinstall:
- Extensions view → CodeGuard → Uninstall
- Restart VSCode
- Reinstall from marketplace
Reset all settings:
```
{
  "codeguard.enabled": false
}
```
- Delete .codeguardrc.json
- Clear cache directory
- Reload window
- Re-enable with default settings

Still having issues? Open an issue on GitHub with the information above.

FilesExpand file tree

TROUBLESHOOTING.md

Latest commit

History

TROUBLESHOOTING.md

File metadata and controls

CodeGuard Troubleshooting Guide

Table of Contents

Extension Not Activating

Symptom

Possible Causes & Solutions

1. Extension Not Installed

2. Extension Disabled

3. Unsupported File Type

4. Extension Crashed

5. Activation Event Not Triggered

Verification Steps

Analysis Issues

Symptom

Issue: Analysis Not Triggering

Issue: Diagnostics Not Appearing

Issue: Analysis Timeout

Issue: Specific Analyzer Not Working

Performance Problems

Symptom

Issue: Slow Analysis

Issue: High CPU Usage

Issue: High Memory Usage

Issue: VSCode Freezing

AI Features Not Working

Symptom

Issue: AI Not Enabled

Issue: Ollama Not Running

Issue: OpenAI/Claude API Errors

Issue: AI Timeout

Issue: Poor AI Suggestions

Cache Issues

Symptom

Issue: Cache Not Working

Issue: Stale Results

Issue: Cache Corruption

Issue: Cache Taking Too Much Space

Configuration Problems

Symptom

Issue: Settings Not Applied

Issue: Invalid Configuration

Issue: Configuration Not Found

Memory Issues

Symptom

Issue: Memory Leak

Issue: Memory Limit Exceeded

False Positives

Symptom

Issue: Too Many False Positives

Issue: Ignoring Not Working

Diagnostic Tools

Enable Debug Logging

Check Extension Status

Profile Performance

Memory Profiling

Network Monitoring

Getting Help

Before Asking for Help

Where to Get Help

Reporting Bugs

Emergency Workarounds