Troubleshooting

Installation Issues

App won't launch

Symptoms: Nothing happens when clicking the app icon

Solutions:

1. Check System Requirements: Verify macOS 12+. Windows/Linux apply once those builds are published.
2. Delete Preferences: rm -rf ~/Library/Application\ Support/Guardian
3. Reinstall: Download fresh installer and reinstall

"Damaged app" on macOS

Cause: macOS Gatekeeper blocking unsigned apps

Solution:

xattr -cr /Applications/Guardian.app

Or go to System Preferences > Security & Privacy and click "Open Anyway"

Authentication Issues

"Invalid API Key" Error

Cause: Key format incorrect or key revoked

Solutions:

1. Verify key is copied completely (no extra spaces)
2. Check key is active in provider console:
   • Anthropic: console.anthropic.com
   • OpenAI: platform.openai.com
3. Generate a new key if necessary
4. Ensure correct provider is selected in Settings > Provider

"Rate Limit Exceeded"

Cause: Too many requests in short time

Solutions:

1. Wait 1 minute for rate limit reset
2. Reduce concurrent activity (pause monitoring, or avoid rapid file saves during large refactors)
3. Switch to a different provider/model temporarily (or use a local provider like Ollama)
4. Check provider dashboard for usage limits and plan/quota settings

"Provider Unavailable"

Cause: Service outage or network issue

Solutions:

1. Check provider status:
   • Anthropic: status.anthropic.com
   • OpenAI: status.openai.com
2. Verify internet connection
3. Check firewall/proxy settings
4. Switch to backup provider if configured

"Model Not Found"

Cause: Selected model deprecated or unavailable

Solutions:

1. Update Guardian to latest version
2. Check available models in provider console
3. Select alternative model in Settings > Provider
4. Verify API key has access to requested model

Scanning Issues

Blank screen during scan

Cause: Antivirus or security software blocking

Solutions:

1. Add Guardian to antivirus exclusions
2. Check macOS Security & Privacy notifications
3. Temporarily disable antivirus for testing
4. Check macOS Security & Privacy settings

Scan is very slow

Causes & Solutions:

Cause	Solution
Large codebase	Narrow the workspace scope to key folders
Too many files	Start with a smaller subset and expand gradually
Insufficient memory	Close other applications, increase RAM
Slow disk	Use SSD, exclude network drives

To improve scan speed:

1. Use ignore patterns in your project (for example .gitignore or Guardian ignore markers):

   node_modules/
   dist/
   build/
   .git/
   *.min.js
   *.bundle.js
   vendor/
   coverage/
   .next/
   

2. Focus on higher-severity findings first to reduce noise
3. Narrow the workspace scope to the most relevant folders

Missing files in scan results

Cause: Ignore patterns too broad

Solution:

1. Check your ignore patterns for overly broad rules
2. Remove overly broad patterns like *.js or src/
3. Add specific exclusions instead:

   # Too broad (removes all JS files)
   *.js
   
   # Specific (better)
   *.min.js
   *.bundle.js
   

Scan crashes or freezes

Solutions:

1. Reduce file size limit by narrowing your workspace scope
2. Temporarily limit the workspace to the most relevant folders
3. Scan smaller directories first
4. Check system resources (CPU/RAM usage)
5. Include the app version and any error messages in your report

Update Issues

Monitor shows empty findings after restart

Cause: The app has not hydrated from the local snapshot yet.

Solutions:

1. Verify the workspace contains .guardian/critiques.json.
2. Relaunch Guardian and wait for the monitor snapshot sync to complete.
3. If the file is missing, run a new scan to regenerate findings.

Version is missing in Updates tab

Cause: latest.json not found or malformed

Solutions:

1. Confirm latest.json exists in distribution release
2. Verify all URLs in latest.json point to public distribution repo
3. Check network connectivity to the update host
4. Manually download from website if needed

Wrong package is recommended

Solutions:

1. Use the manual package list on Download page
2. Test in a clean browser profile
3. Check if user agent is being modified by extensions
4. Manually select correct package for your OS

Update fails to install

Solutions:

1. Check disk space: Ensure 500MB+ free space
2. Close Guardian: Quit app completely before updating
3. Permissions: Ensure write access to /Applications
4. Manual update: Download installer from website

"Update verification failed"

Cause: Corrupted download or signature mismatch

Solutions:

1. Delete downloaded update package
2. Retry update
3. Download fresh installer from website
4. Check system date/time (affects certificate validation)

Guru (AI Assistant) Issues

No response from Guru

Solutions:

1. Check API key in Settings > Provider
2. Start monitoring to validate the provider connection
3. Verify internet connection
4. Check provider status page
5. Try switching to backup provider

Guru gives generic answers

Solutions:

1. Include more context in prompts
2. Reference specific files or line numbers
3. Try a different model or provider for deeper analysis

Slow Guru responses

Solutions:

1. Reduce input size and focus on a smaller code snippet
2. Switch to faster model (Haiku instead of Opus)
3. Check internet connection speed
4. Close other bandwidth-intensive applications

Incorrect suggestions from Guru

Solutions:

1. Add more constraints and context to your prompt (file path, expected behavior, failure mode)
2. Ask for the FULL updated file content only (no diff markers, no markdown) when you need copy/paste-ready output
3. Try a different model/provider if you need deeper reasoning
4. Check if the right model is selected for the task

Performance Issues

High CPU usage

Solutions:

1. Disable auto-scan on file save
2. Reduce scan frequency
3. Close unused projects
4. Limit concurrent scans

High memory usage

Solutions:

1. Restart Guardian to clear in-memory state
2. Close unused projects
3. Reduce max file size limit
4. Restart Guardian periodically

App is sluggish

Solutions:

1. Restart the application
2. Reduce number of open projects
3. Reduce background tasks and close unused apps

Network Issues

Can't connect to AI provider

Check:

1. Internet connection
2. Firewall settings
3. Proxy configuration
4. VPN interference

Proxy Configuration:

# Set environment variables
export HTTPS_PROXY=http://proxy.company.com:8080

Or configure your system proxy settings

Certificate errors

Cause: Corporate firewall intercepting HTTPS

Solutions:

1. Install corporate root certificate
2. Configure proxy settings
3. Contact IT for firewall exceptions

Data Issues

Lost scan history

Recovery:

1. Check if data folder exists: ~/Library/Application Support/Guardian/
2. Restore from backup if available
3. Re-scan projects to rebuild history

Settings reset unexpectedly

Causes:

1. Corrupted preferences file
2. App crash during write
3. Disk space issues

Solutions:

1. Re-open Guardian and re-save your Provider settings if needed
2. Restart the application to reload settings

Getting Help

If issues persist:

1. Check Documentation: Review relevant guide sections
2. Support Details: Include app version and any error messages
3. Community: Community forum or internal support channel
4. Support Email: contact@senoldogan.dev

Include in support request:

• Guardian version
• Operating system and version
• Steps to reproduce
• Error messages
• Exported logs (if possible)