Troubleshooting Guide

Administrator Privileges Issues

Frameshift requires administrator access to modify system settings and apply optimizations. Most optimization-related issues stem from insufficient permissions.

Problem: Optimizations Won't Apply

Symptoms: Clicking "Apply" on optimization categories shows errors or has no effect.

Solution:

1. Check Admin Status

   Look at the Frameshift window title bar. If it doesn't say "(Administrator)" after "Frameshift", you don't have admin rights.

2. Restart as Administrator

   Close Frameshift completely. Right-click the Frameshift shortcut or executable and select "Run as administrator".

3. Enable Start on Boot (Optional)

   If you enable "Start on Boot" in settings, Frameshift will automatically launch with admin privileges on every Windows startup.

Optimization Issues

Problem: Performance Got Worse After Optimizing

Symptoms: Lower FPS, stuttering, or system instability after applying optimizations.

Solution:

• Revert the optimization: Navigate to the problematic optimization category and click "Revert". This restores all previous settings.
• Restart your system: Some optimizations require a reboot to take full effect. Restart Windows and test again.
• Apply categories individually: Instead of applying all 6 categories at once, apply them one at a time and test performance after each.
• Use system restore: If reverting doesn't work, use Windows System Restore to roll back to a restore point created before optimization.

Problem: Specific Optimization Category Fails

Symptoms: One optimization category shows error messages while others work fine.

Solution by Category:

Game Detection Issues

Problem: Game Not Detected

Symptoms: Frameshift doesn't show the "Game Detected" event when you launch a supported game.

Solution:

1. Check Game Database

   Ensure your game is in the supported games list. Frameshift supports 100+ games, but some newer or less popular titles may not be included yet.

2. Verify Game is Running

   Open Task Manager and confirm the game executable is running. Some games launch a launcher first, which isn't the actual game process.

3. Manually Add Game to Database

   Navigate to %APPDATA%\Frameshift\gameDatabase.json and add your game's executable manually following the existing format.

4. Restart Frameshift

   After modifying the game database, restart Frameshift to reload the updated game list.

{
  "appid": "0",
  "name": "Your Game Name",
  "platform": "Standalone",
  "executables": ["YourGame.exe", "YourGame_x64.exe"],
  "popularity": {
    "players": 0,
    "owners": "0 .. 0"
  }
}

Problem: Auto-Tuning Not Working

Symptoms: Game is detected but automatic optimizations aren't applied.

Solution:

• Open Settings and ensure "Auto-Tuning" is enabled
• Check that "Game Mode" is enabled in settings
• Verify Frameshift is running with administrator privileges
• Try manually applying optimizations from the Optimizations tab

Problem: Game Won't Start After Optimization

Symptoms: A game crashes immediately on launch, shows errors, or doesn't start at all after applying optimizations.

Solution:

• Revert to restore point: Use Windows System Restore to roll back to the most recent restore point. Frameshift automatically creates restore points before each optimization category, so you can safely revert all changes.
• Revert specific categories: Navigate to the Optimizations tab and click "Revert" on each optimization category one at a time, testing the game after each revert to identify the problematic category.
• Check anti-cheat compatibility: Some anti-cheat systems may flag system modifications. If the game uses anti-cheat software (like EAC, BattlEye, Vanguard), revert all optimizations before playing.

Overlay Issues (Pro)

Problem: Overlay Not Appearing In-Game

Symptoms: In-game overlay doesn't show even though you have Frameshift Pro.

Solution:

• Verify Pro status: Check if your Pro license is active in Settings > Account
• Check overlay visibility: Ensure the overlay is enabled in Settings > Overlay
• Test overlay position: The overlay might be off-screen. Reset position to default (-420, 20) in settings
• Anti-cheat compatibility: Some games with invasive anti-cheat (Valorant, FACEIT) may block overlays. This is a game limitation, not a Frameshift issue.
• Fullscreen vs Borderless: Try switching your game to borderless windowed mode instead of exclusive fullscreen

Problem: Can't Click Overlay Elements

Symptoms: Overlay appears but you can't interact with it.

Solution:

• Press the overlay hotkey (default: Alt+Q) to toggle interaction mode
• When interaction mode is OFF, the overlay is click-through (game receives clicks)
• When interaction mode is ON, you can click overlay elements but not the game

Monitoring & Analytics Issues

Problem: Metrics Not Updating

Symptoms: Dashboard shows 0% CPU/GPU/RAM or metrics are frozen.

Solution:

• Wait a few seconds: Metrics use round-robin polling. Each metric updates every ~333ms when focused
• Check native module: The monitoring module requires C++ bindings. Reinstall Frameshift if metrics never appear
• GPU drivers: GPU metrics require vendor-specific APIs. Update NVIDIA, AMD, or Intel GPU drivers
• Restart Frameshift: Sometimes the monitoring service needs a restart

Problem: Analytics Not Recording

Symptoms: Analytics tab shows "No data available" even after using Frameshift for days.

Solution:

• Verify "Enable Analytics" is turned on in Settings > Analytics
• Check disk space - analytics database needs at least 50MB free space
• Database corruption - delete %APPDATA%\Frameshift\analytics.db to start fresh (loses history)
• Wait 5 seconds - analytics collection runs every 5 seconds, not instantly

Settings & Configuration Issues

Problem: Settings Not Saving

Symptoms: Settings reset to default every time you restart Frameshift.

Solution:

• Registry permissions: Ensure Frameshift has permission to write to HKEY_CURRENT_USER\Software\Frameshift
• Run as admin: Settings persistence requires admin privileges on some systems
• Antivirus blocking: Some security software blocks registry writes. Add Frameshift to your antivirus whitelist

Problem: Start on Boot Not Working

Symptoms: "Start on Boot" is enabled but Frameshift doesn't launch on Windows startup.

Solution:

• Check if another security software is blocking startup programs
• Open Task Manager > Startup tab and verify Frameshift is listed and enabled
• Manually add Frameshift to startup: Press Win+R, type shell:startup, create a shortcut to Frameshift.exe
• Right-click the shortcut > Properties > Advanced > Check "Run as administrator"

Update Issues

Problem: Update Check Fails

Symptoms: "Check for Updates" shows an error or timeout.

Solution:

• Check your internet connection
• Firewall or antivirus may be blocking Frameshift from accessing the update server (Cloudflare R2 CDN)
• Manually download the latest version from the official website
• Disable VPN temporarily and try again

Problem: Update Downloaded But Won't Install

Symptoms: Update notification appears but clicking "Install" does nothing or shows an error.

Solution:

• Close Frameshift completely and manually run the downloaded installer from %TEMP%\Frameshift
• Ensure no other instance of Frameshift is running (check Task Manager)
• Delete the downloaded update and try downloading again

System Tray Issues

Problem: Frameshift Disappears When Minimized

Symptoms: Closing the window makes Frameshift disappear completely instead of going to system tray.

Solution:

• Enable "Run in Background" in Settings > General
• Check your system tray (bottom-right corner of taskbar) - Frameshift icon should be there
• Click the up arrow (^) in system tray to show hidden icons
• Left-click the Frameshift icon to restore the window

Reverting Changes

How to Completely Revert All Optimizations

If you want to undo all changes and restore your system to its pre-optimization state:

1. Revert Each Category

   Navigate to the Optimizations tab and click "Revert" on each optimization category you've applied (Network, GPU, CPU, Storage, Memory, System).

2. Restart Your System

   After reverting all categories, restart Windows to ensure all settings take effect.

3. Use System Restore (If Needed)

   If reverting doesn't fully restore your system, use Windows System Restore to roll back to the restore point created before optimization. Search for "System Restore" in Windows Start menu and follow the wizard.

Performance Issues with Frameshift Itself

Problem: Frameshift Uses Too Much CPU

Symptoms: Frameshift consumes more than 5% CPU while idle or causes system slowdown.

Solution:

• Increase metric update rate in Settings > Monitoring (e.g., from 250ms to 500ms)
• Reduce graph history length to 300 points instead of 900
• Disable analytics if you don't need historical data
• Minimize Frameshift to system tray - monitoring slows down when window is hidden

Still Having Issues?

If your problem isn't covered here, try these general troubleshooting steps:

• Restart Frameshift: Close and reopen the application
• Restart Windows: Many optimizations require a reboot
• Reinstall Frameshift: Uninstall, download the latest version, and reinstall
• Check logs: View Frameshift logs at %APPDATA%\Frameshift\logs\ for detailed error messages
• Disable antivirus temporarily: Some security software interferes with system optimizations