Troubleshooting Guide

This guide covers common issues and their solutions when using SceneShift.

General Issues

SceneShift Won't Start

Symptom: Double-clicking the executable does nothing or shows an error.

Common Causes and Solutions:

  1. Not running as Administrator
  2. Right-click SceneShift.exe
  3. Select "Run as administrator"

  4. Configure your shortcut to always run as admin (see Installation guide)

  5. Missing dependencies

  6. Install Visual C++ Redistributable (x64)
  7. Download from Microsoft's website

  8. Restart computer after installation

  9. Antivirus blocking execution

  10. Check your antivirus quarantine
  11. Add SceneShift.exe to the exclusion list

  12. Unsigned executables may trigger false positives

  13. Corrupted download

  14. Re-download the executable
  15. Verify file size matches the release page
  16. Extract again if using zip file

Configuration File Errors

Symptom: Error message about config.yaml on startup.

Solutions:

  1. Corrupted configuration
  2. Delete config.yaml
  3. SceneShift will regenerate it on next launch

  4. Your apps and presets will be lost (back up config.yaml regularly)

  5. Invalid YAML syntax

  6. Open config.yaml in a text editor
  7. Check for proper indentation (use spaces, not tabs)
  8. Ensure colons have a space after them

  9. Verify quotes are balanced

  10. Permission issues

  11. Ensure SceneShift folder is not in a protected location
  12. Move to Documents folder if in Program Files
  13. Check folder permissions allow write access

Process Management Issues

Process Won't Terminate

Symptom: Attempting to kill a process shows an error or does nothing.

Common Causes:

  1. Process is protected
  2. Check for shield icon next to process name
  3. Protected processes cannot be terminated for safety

  4. Remove from exclusion list only if you understand the risk

  5. Insufficient privileges

  6. Verify SceneShift is running as Administrator
  7. Some system services require additional permissions

  8. Try suspend mode instead of kill mode

  9. Process name mismatch

  10. Verify the process name exactly matches Task Manager
  11. Process names are case-insensitive but must be spelled correctly

  12. Some apps have multiple processes (check all variants)

  13. Protected by another application

  14. Antivirus software may protect certain processes
  15. Game anti-cheat systems prevent process termination
  16. Temporarily disable protection to manage these processes

Suspend Operation Fails

Symptom: Attempting to suspend a process shows an error.

Solutions:

  1. Modern Windows app (UWP)
  2. UWP apps cannot be suspended by third-party tools
  3. These apps use different process architecture

  4. Use kill mode instead for UWP applications

  5. System service

  6. Windows services require special handling
  7. SceneShift cannot suspend most system services

  8. Check if process is in exclusion list

  9. Already suspended

  10. Check status indicator
  11. If already showing suspended, no action needed
  12. Use resume mode to unsuspend first

Resume Operation Fails

Symptom: Resume doesn't work or resumes wrong instance.

Common Causes:

  1. Process no longer exists
  2. Original process may have been terminated
  3. Windows may have reused the Process ID

  4. SceneShift validates PID before resuming

  5. Multiple instances running

  6. SceneShift tracks specific PIDs
  7. Newly launched instances won't be affected

  8. This is intentional behavior to prevent mistakes

  9. Process already running

  10. Check status indicator
  11. If showing running, already resumed
  12. May need to suspend again first

Restore Operation Fails

Symptom: Applications don't launch when restored.

Common Causes:

  1. Executable moved or deleted
  2. Verify the executable path in app configuration
  3. Edit the app entry and update the path

  4. Use Ctrl+F to search for the current location

  5. Insufficient permissions

  6. Some applications require specific user context
  7. Try running SceneShift as the user who installed the app

  8. Administrator privileges may not be enough for some apps

  9. Application requires specific launch arguments

  10. SceneShift launches without arguments
  11. Add a launcher script if arguments are needed

  12. Point the executable path to the script

  13. Application prevents multiple instances

  14. Some apps only allow one running instance
  15. If already running, restore will fail
  16. Check Task Manager before attempting restore

Interface Issues

Text Appears Garbled or Unreadable

Symptom: Strange characters or missing text in the interface.

Solutions:

  1. Terminal encoding issue
  2. Run SceneShift in Windows Terminal instead of CMD
  3. Windows Terminal has better Unicode support

  4. PowerShell also provides better rendering

  5. Font doesn't support icons

  6. Install a font with icon support (Cascadia Code, Fira Code)
  7. Configure your terminal to use the new font

  8. Restart SceneShift after font installation

  9. Console window too small

  10. Maximize the terminal window
  11. SceneShift requires minimum 80x24 character display
  12. Resize manually if auto-resize doesn't work

Colors Don't Display Correctly

Symptom: All text appears in the same color or colors are wrong.

Solutions:

  1. Terminal doesn't support colors
  2. Use Windows Terminal or PowerShell
  3. CMD has limited color support

  4. Consider switching terminals for better experience

  5. Theme issue

  6. Press 't' to change theme
  7. Try a different theme to verify
  8. Check theme.yaml for corrupted values

UI Updates Slowly or Freezes

Symptom: Interface is unresponsive or laggy.

Solutions:

  1. Too many processes tracked
  2. SceneShift updates stats for all apps
  3. Reduce number of configured apps

  4. Stats are cached but updates still consume resources

  5. Terminal performance

  6. Windows Terminal generally performs better than CMD
  7. Try a different terminal emulator

  8. Close other terminal sessions

  9. Background CPU usage

  10. Other applications may be consuming resources
  11. Check Task Manager for CPU bottlenecks
  12. Close unnecessary background apps

Feature-Specific Issues

Presets Don't Work

Symptom: Pressing preset hotkey does nothing or selects wrong apps.

Solutions:

  1. Hotkey conflict
  2. Verify hotkey doesn't conflict with existing keybindings
  3. Use single character or number

  4. Avoid keys used by Windows or terminal

  5. App names don't match

  6. Preset uses app names, not process names
  7. Check spelling in preset configuration

  8. Names are case-sensitive in config.yaml

  9. Preset not saved

  10. Verify preset appears in preset manager
  11. Check config.yaml contains the preset
  12. Try recreating the preset

Import Configuration Fails

Symptom: Attempting to import a profile shows an error.

Solutions:

  1. Invalid JSON file
  2. Verify file is valid JSON
  3. Use a JSON validator online

  4. Check for syntax errors in the file

  5. Version incompatibility

  6. Profile may be from newer SceneShift version
  7. Update SceneShift to latest version

  8. Check metadata.sceneshift_version in profile

  9. File not found

  10. Ensure profile file is in SceneShift directory
  11. Check filename matches exactly (case-sensitive)

  12. Verify file wasn't moved or deleted

  13. No profiles in list

  14. Files must be named sceneshift-profile-*.json
  15. Check file extensions are .json not .txt
  16. Export a test profile to verify filename format

Undo Doesn't Work

Symptom: Undo operation fails or shows error.

Solutions:

  1. Nothing to undo
  2. Undo only works for most recent operation
  3. History is cleared when SceneShift exits

  4. Verify an operation was actually performed

  5. Executable paths missing

  6. Undo kill requires valid executable paths
  7. Edit app configurations to add missing paths

  8. Cannot restore apps without path information

  9. Processes no longer exist

  10. Undo suspend requires original PIDs to exist
  11. If processes were terminated externally, undo fails
  12. This is expected behavior

Session History Empty

Symptom: Pressing 'h' shows no history.

Solutions:

  1. No operations performed
  2. History only tracks kill/suspend/resume/restore
  3. App management doesn't create history entries

  4. Perform an operation to populate history

  5. History cleared on exit

  6. Session history is not persistent
  7. Intentional behavior to keep memory usage low
  8. Export logs if you need permanent record

Performance Issues

High CPU Usage

Symptom: SceneShift itself consumes significant CPU.

Solutions:

  1. Stats collection overhead
  2. Stats update in background
  3. Cached for 2 seconds to minimize impact

  4. Consider reducing number of tracked apps

  5. Large process list

  6. SceneShift enumerates all processes periodically
  7. This is normal behavior
  8. CPU usage should be < 5% when idle

High Memory Usage

Symptom: SceneShift uses more RAM than expected.

Solutions:

  1. Large configuration
  2. Many apps and presets increase memory use
  3. This is normal and generally under 50 MB

  4. Not significant compared to other applications

  5. Memory leak

  6. Restart SceneShift to clear
  7. Report issue on GitHub if it persists
  8. Monitor memory over time to verify

Getting Additional Help

If your issue is not covered here:

  1. Check the GitHub Issues page
  2. Search for similar problems
  3. Create a new issue with:
  4. SceneShift version
  5. Windows version
  6. Detailed description of the problem
  7. Steps to reproduce
  8. Error messages or screenshots

For configuration help, see the Configuration Guide in the documentation.

For general usage questions, see the Usage Guide.