Troubleshooting

Having trouble with SnapBack? This guide covers common issues and their solutions.

Common Issues

Extension Not Installing

Problem: The SnapBack extension fails to install in VS Code.

Solutions:

1. Ensure you’re using VS Code version 1.70 or later
2. Check your internet connection
3. Try restarting VS Code and installing again
4. Clear VS Code’s extension cache:

   Copy# Close VS Code
   # Navigate to your VS Code user data directory
   # Delete the "extensions" folder
   # Restart VS Code and try again

Snapshots Not Being Created

Problem: SnapBack isn’t creating snapshots when you save files.

Solutions:

1. Check that the SnapBack extension is enabled
2. Verify that you have permission to write to the snapshot storage location
3. Check the SnapBack output panel for error messages:

   Copy# In VS Code, go to View → Output
   # Select "SnapBack" from the dropdown

4. Ensure your file isn’t in an ignored pattern (check .snapbackignore)

AI Detection False Positives

Problem: Guardian AI is flagging code that isn’t actually a risk.

Solutions:

1. Add the file or pattern to your .snapbackignore file:

   Copy// .snapbackignore
   {
     "aiDetection": {
       "ignorePatterns": [
         "**/mock-data/**",
         "**/*.example.js"
       ]
     }
   }

2. Adjust sensitivity levels in your configuration:

   Copy// .snapbackconfig
   {
     "aiDetection": {
       "sensitivity": "medium" // or "low"
     }
   }

3. Provide feedback through the VS Code extension

Performance Issues

Problem: SnapBack is slowing down VS Code or taking too long to create snapshots.

Solutions:

1. Check if you have an excessive number of snapshots:

   Copysnapback stats

2. Clean up old snapshots:

   Copysnapback cleanup --keep 30d

3. Exclude large files or directories:

   Copy// .snapbackignore
   {
     "snapshots": {
       "ignorePatterns": [
         "**/node_modules/**",
         "**/dist/**",
         "*.log"
       ]
     }
   }

Error Codes

ERR_001: Storage Permission Denied

Cause: SnapBack doesn’t have permission to write to the snapshot storage location.

Solution:

1. Check that the storage directory exists and is writable
2. Run VS Code with appropriate permissions
3. Change the storage location in settings:

   Copy// VS Code settings.json
   {
     "snapback.storagePath": "/path/to/writable/directory"
   }

ERR_002: Invalid Configuration

Cause: There’s a syntax error in one of your SnapBack configuration files.

Solution:

1. Validate your JSON syntax in .snapbackconfig and .snapbackignore
2. Use a JSON validator tool to check for errors
3. Refer to the configuration documentation for correct format

ERR_003: Network Error (CLI)

Cause: The CLI tool can’t connect to required services.

Solution:

1. Check your internet connection
2. Verify that required ports are not blocked by firewall
3. Try using the CLI tool in offline mode if available

Platform-Specific Issues

macOS

Issue: SnapBack extension not working on macOS.

Solutions:

1. Ensure you’re using the official VS Code build (not VS Code - Insiders unless specified)
2. Check that you’ve granted VS Code access to your files in System Preferences
3. Try reinstalling the extension

Windows

Issue: Path length issues on Windows.

Solutions:

1. Enable long path support in Windows:

   Copy# Run as Administrator
   reg add HKLM\SYSTEM\CurrentControlSet\Control\FileSystem /v LongPathsEnabled /t REG_DWORD /d 1

2. Use a shorter project path
3. Configure SnapBack to use a different storage location

Linux

Issue: Permission issues with snapshot storage.

Solutions:

1. Ensure the user running VS Code has write permissions to the storage directory
2. Check that the file system supports the required operations
3. Consider using a different storage location

Debugging Steps

Enable Debug Logging

To get more detailed information about what SnapBack is doing:

1. In VS Code, open Settings (Ctrl+, or Cmd+,)
2. Search for “snapback debug”
3. Enable debug logging
4. Check the Output panel for detailed logs

Check System Requirements

Ensure your system meets the minimum requirements:

• VS Code: Version 1.70 or later
• Node.js: Version 14 or later (for CLI)
• Operating System: Windows 10+, macOS 10.14+, or Linux with glibc 2.17+

Verify Installation

To verify that SnapBack is properly installed:

Copy# Check VS Code extension
code --list-extensions | grep snapback

# Check CLI tool
snapback --version

# Check configuration
snapback config validate

Getting Help

If you’re still having issues after trying these solutions:

1. Check the Community:

   • GitHub Issues
   • Discord Community

2. Contact Support:

   • Email: support@snapback.dev
   • Include:
     • SnapBack version
     • VS Code version
     • Operating system
     • Error messages
     • Steps to reproduce the issue

3. Provide Debug Information:

   Copy# Generate a debug report
   snapback debug report --output debug-report.json

Related Documentation

• Quick Start Guide - Get up and running quickly
• Protection Levels - Configure file protection
• AI Detection - Understand risk analysis
• Session Time-Travel - Navigate your coding history