🔧 DeckSaves Troubleshooting Guide

Quick Solutions for Common Issues

🚨 Emergency Save Recovery

If you've lost your save files and need immediate help:

1. Check version history - Click "📋 History" for the affected game
2. Look for recent versions - Find the most recent backup before the loss
3. Restore immediately - Click "↩️ Restore" next to the version
4. Verify restoration - Launch the game to confirm saves are restored

⚡ Quick Fixes

Application Won't Start

# Windows: Run as administrator
Right-click DeckSaves → "Run as administrator"

# macOS: Remove quarantine
xattr -r -d com.apple.quarantine /Applications/DeckSaves.app

# Linux: Check permissions
chmod +x DeckSaves-Linux-x64.AppImage

Sync Failing

1. Check internet connection
2. Verify storage configuration in Storage tab
3. Test connection using "Test S3 Connection" button
4. Switch to Local Storage temporarily if S3 issues persist

Can't Add Game

1. Verify save paths exist and are accessible
2. Try browsing to select paths instead of typing
3. Check file permissions on save directories
4. Restart DeckSaves and try again

Detailed Troubleshooting

🔄 Sync Issues

"Failed to sync: dispatch failure"

Symptoms: Sync operations fail with network-related errors

Causes & Solutions:

1. Network connectivity:

   • Check internet connection
   • Try pinging AWS S3 endpoints: ping s3.amazonaws.com
   • Test with different network (mobile hotspot)

2. AWS configuration:

   • Verify AWS credentials in Storage tab
   • Test S3 connection using built-in test
   • Check IAM permissions for S3 access
   • Verify bucket exists and region is correct

3. Firewall/Proxy issues:

   • Check corporate firewall settings
   • Configure proxy if behind corporate network
   • Try temporarily disabling antivirus/firewall

Quick Fix: Switch to Local Storage in Storage tab

"Version not found in manifest"

Symptoms: Cannot restore, pin, or delete specific versions

Causes & Solutions:

1. Manifest corruption:

   # Check manifest file
   # Location: ~/.decksaves/local_storage/manifests/
   cat ~/.decksaves/local_storage/manifests/GameName.json
   

2. Version ID mismatch:

   • Try Smart Sync to rebuild manifests
   • Check for duplicate game entries
   • Verify game names match exactly

3. Storage inconsistency:

   • Run cleanup to remove orphaned versions
   • Verify storage location has proper permissions
   • Check available disk space

"Game not found in configuration"

Symptoms: Sync fails because game isn't recognized

Solutions:

1. Re-add the game:

   • Remove game from list
   • Add again with exact same name
   • Verify save paths are correct

2. Check configuration file:

   # View current configuration
   cat ~/.decksaves/config.json | grep -A 10 "games"
   

3. Configuration corruption:

   • Export working configuration as backup
   • Restart application to regenerate config
   • Import games from backup

📁 File System Issues

"Permission denied"

Symptoms: Cannot access save files or storage locations

Solutions:

1. Windows:

   # Run as administrator
   # Check folder permissions
   icacls "C:\Users\YourName\Documents\My Games\GameName" /T
   

2. macOS:

   # Give full disk access in System Preferences
   # Check permissions
   ls -la ~/Library/Application\ Support/GameName/
   

3. Linux:

   # Fix permissions
   chmod -R 755 ~/.local/share/gamename/
   # Check ownership
   ls -la ~/.local/share/gamename/
   

"Path not found" or "Directory doesn't exist"

Solutions:

1. Verify paths exist:

   • Browse to save locations manually
   • Check for typos in path names
   • Look for case sensitivity issues (Linux/macOS)

2. Game installation issues:

   • Verify game is properly installed
   • Check if game has been run at least once
   • Look for saves in alternative locations

3. Path format issues:

   # Windows format
   C:\Users\YourName\Documents\My Games\GameName\
   
   # macOS format  
   /Users/YourName/Library/Application Support/GameName/
   
   # Linux format
   /home/username/.local/share/gamename/
   

☁️ Storage Issues

S3 Connection Problems

Symptoms: "Failed to connect to S3" or similar AWS errors

Diagnostic Steps:

1. Test AWS CLI (if installed):

   aws s3 ls s3://your-bucket-name --region your-region
   

2. Check credentials:

   • Verify Access Key ID and Secret Access Key
   • Ensure IAM user has S3 permissions
   • Check for expired credentials

3. Verify bucket configuration:

   • Bucket exists in specified region
   • Bucket name is globally unique
   • No bucket policies blocking access

Required IAM Permissions:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "s3:GetObject",
                "s3:PutObject", 
                "s3:DeleteObject",
                "s3:ListBucket",
                "s3:GetBucketLocation"
            ],
            "Resource": [
                "arn:aws:s3:::your-bucket-name",
                "arn:aws:s3:::your-bucket-name/*"
            ]
        }
    ]
}

Local Storage Issues

Symptoms: Cannot write to or read from local storage directory

Solutions:

1. Check disk space:

   # Check available space
   df -h ~/.decksaves/
   

2. Verify permissions:

   # Create test file
   touch ~/.decksaves/test_file
   rm ~/.decksaves/test_file
   

3. Path issues:

   • Ensure path doesn't contain special characters
   • Check for spaces in directory names
   • Verify path length limits (Windows: 260 chars)

🎮 Game-Specific Issues

Steam Games Not Detected

Symptoms: "Discover Steam Games" finds no games or wrong paths

Solutions:

1. Steam installation location:

   # Default Steam locations
   # Windows: C:\Program Files (x86)\Steam\
   # macOS: ~/Library/Application Support/Steam/
   # Linux: ~/.steam/ or ~/.local/share/Steam/
   

2. Multiple Steam libraries:

   • Check all Steam library folders
   • Verify steamapps folders exist
   • Look for games in custom install locations

3. Registry issues (Windows):

   # Check Steam registry key
   reg query "HKEY_CURRENT_USER\Software\Valve\Steam" /v SteamPath
   

Save Files Not Syncing

Symptoms: Sync completes but save files unchanged

Diagnostic Steps:

1. Verify save paths:

   • Check if game creates saves in expected location
   • Look for cloud save conflicts
   • Verify game is actually creating save files

2. File timing issues:

   • Check file modification times
   • Look for files being locked by the game
   • Verify file permissions allow reading

3. Game-specific issues:

   • Some games encrypt save files
   • Some games use Steam Cloud exclusively
   • Some games have unusual save formats

🔧 Application Issues

High Memory Usage

Symptoms: DeckSaves using excessive RAM

Solutions:

1. Large save files:

   • Check for unusually large save files
   • Enable compression in storage settings
   • Consider local storage for large files

2. Memory leaks:

   • Restart DeckSaves regularly
   • Update to latest version
   • Report issue with memory usage details

Slow Performance

Symptoms: Syncs take very long time

Optimization:

1. Network speed:

   • Test internet connection speed
   • Consider local storage for better performance
   • Sync during off-peak hours

2. File size optimization:

   • Enable compression
   • Clean up old save files
   • Use versioned sync strategically

3. System resources:

   • Close other applications during sync
   • Check available disk space
   • Ensure sufficient RAM available

📋 Logs and Diagnostics

Enabling Debug Logging

To get detailed information for troubleshooting:

1. Environment variable method:

   # Windows (Command Prompt)
   set RUST_LOG=debug
   DeckSaves.exe
   
   # Windows (PowerShell)
   $env:RUST_LOG="debug"
   .\DeckSaves.exe
   
   # macOS/Linux
   export RUST_LOG=debug
   ./DeckSaves
   

2. Application logs location:

   • Windows: %APPDATA%\DeckSaves\logs\
   • macOS: ~/Library/Application Support/DeckSaves/logs/
   • Linux: ~/.config/DeckSaves/logs/

Understanding Log Messages

Common log patterns and their meanings:

INFO  core: Added game: GameName
# Game successfully added to configuration

ERROR core: Failed to sync file with versioning: Failed to upload file to storage: dispatch failure
# Network connectivity issue with cloud storage

DEBUG tauri_ui::commands: sync_game_with_versioning called for: GameName
# Versioned sync operation started

WARN  core: Save path does not exist: /path/to/saves
# Game save directory not found

🆘 Getting Additional Help

Before Reporting Issues

1. Collect information:

   • DeckSaves version number
   • Operating system and version
   • Error messages (exact text)
   • Steps to reproduce the issue

2. Try basic troubleshooting:

   • Restart the application
   • Restart your computer
   • Try with a simple test game
   • Test with local storage

3. Gather logs:

   • Enable debug logging
   • Reproduce the issue
   • Collect relevant log files

Reporting Bugs

When creating a GitHub issue, include:

• Clear description of the problem
• Steps to reproduce the issue
• Expected vs actual behavior
• System information (OS, version, etc.)
• Log files (with debug enabled)
• Configuration files (remove sensitive info)

Community Support

• GitHub Discussions: General questions and community help
• Discord Server: Real-time chat support