Troubleshooting

Linux troubleshooting

Start with the Linux troubleshooting checklist for executable permissions, FUSE, paths, Flatpak, Wayland, and support details. Windows system tools below apply to Windows.

Running into issues? Don't worry - we've got you covered. This guide walks through common problems and how to fix them. Most issues have simple solutions, and we'll help you get back to gaming quickly.

Before You Start

When something isn't working, these quick checks solve most problems:

Restart HyperHQ and HyperSpin Many issues resolve with a simple restart. Close everything, reopen, and try again.

Check the Logs HyperHQ keeps detailed logs that explain what's happening. Go to Settings > View Logs to see error messages and warnings.

Verify File Paths Most issues come down to paths. Double-check that folders exist and files are where HyperHQ expects them.

Test Outside HyperSpin If a game won't launch, try running the emulator directly. This tells you if it's an emulator issue or a HyperHQ configuration issue.

Installation Problems

HyperHQ Won't Install

Antivirus Blocking Installation Some antivirus software flags installers as suspicious:

1. Temporarily disable your antivirus
2. Run the HyperHQ installer
3. Re-enable antivirus after installation
4. Add HyperHQ to your antivirus exclusions

Windows SmartScreen Warning If Windows SmartScreen blocks the installer:

1. Click "More info" on the warning
2. Click "Run anyway"
3. HyperHQ is safe - this happens with new software releases

Installation stops before completion

1. Confirm the package matches your operating system and CPU architecture.
2. Download a fresh copy and verify the release checksum where provided.
3. Check free space and write access to the chosen folder.
4. On Windows, follow the installer's elevation prompt if requested.
5. On Linux, extract the setup ZIP and double-click the .run file as your normal user. If blocked, open Properties → Permissions and enable Allow executing file as program or Is executable. Check mount restrictions if execution still fails.
6. Read the installer or terminal error before retrying.

A plugin reports a missing runtime

Use the runtime required by the specific plugin release. Windows .NET Framework packages do not satisfy Linux .NET dependencies. Install the matching Linux plugin package or its declared Linux runtime.

HyperHQ is missing after installation

Check	Windows	Linux
Application menu	Search the Start menu for HyperHQ	Search your desktop application menu for HyperHQ
Default application folder	C:/ProgramData/HyperSpin/HyperHQ/	~/HyperSpin/HyperHQ/
Missing shortcut	Create a shortcut from the installed application	Rerun user-space setup for desktop integration or launch from the extracted app folder

Use your selected installation path if different. Linux setup uses ~/HyperSpin/HyperHQ regardless of XDG_DATA_HOME. An extracted archive does not provide the same desktop integration as setup.

Setup Wizard Issues

Can't Sign In to HyperSpin Account

Invalid Credentials Make sure you're using the right email and password:

1. Verify your caps lock isn't on
2. Try resetting your password at HyperSpin-fe.com
3. Make sure you've created an account (it's free!)

Network Connection Error If you can't connect at all:

1. Check your internet connection
2. Try disabling VPN temporarily
3. Check your firewall isn't blocking HyperHQ
4. Verify HyperSpin-fe.com is accessible in your browser

Account Not Activated New accounts need email verification:

1. Check your email for activation link
2. Look in spam/junk folders
3. Request a new activation email if needed

EmuMovies Login Fails

Account access

EmuMovies uses a separate account. Free accounts provide artwork downloads. Supporting membership adds access to video sync and other premium content.

1. Confirm your login works at EmuMovies.
2. Check membership access when a premium media download fails.
3. Separate login errors from unavailable media or expired membership.

Wrong Credentials EmuMovies credentials are separate from HyperSpin:

• Use your EmuMovies username (not email)
• Use your EmuMovies password (different from HyperSpin)

Connection Issues If the login keeps failing:

1. Skip it for now - you can add it later in Settings
2. Try again after setup completes
3. Verify EmuMovies website is accessible

Plugin Installation Fails During Setup

Network Timeout If plugin downloads time out:

1. Check your internet speed
2. Try again - the installer resumes where it left off
3. Temporarily disable any download throttling software

Disk Space Make sure you have enough space:

• Plugins need ~500MB
• Check the drive where you're installing HyperSpin

Corrupted Download If specific plugins fail repeatedly:

1. Complete setup without them
2. Install them manually later from Settings > Plugins
3. Check Settings > View Logs for specific error messages

Can't Choose HyperSpin Folder

Permission denied

1. Choose a folder writable by your normal user.
2. On Windows, review Properties, Security for the selected folder and use the app's scoped permission repair when offered.
3. On Linux, check ownership, write access, executable permission, and mount options. Keep app binaries off noexec storage.
4. Use the configured HyperSpin root. Default roots are C:/ProgramData/HyperSpin/ on Windows and ~/HyperSpin/ on Linux.

Path or mount problem

• Windows: Shorten deeply nested paths when a tool reports a path-length error.
• Linux: Match filename case and confirm external drives are mounted at the saved path.
• Flatpak emulators: Grant access to the specific ROM and BIOS folders.
• Both: Open the saved path in your file manager and confirm the files exist.

Systems Not Showing Games

This is one of the most common issues. Here's how to fix it:

No Games Appear After Adding System

ROM Path Not Set

1. Go to your system's settings
2. Check the Games tab
3. Verify you've added at least one ROM path
4. Click "Add Path" and browse to your ROM folder

Wrong File Extensions Make sure extensions match your files:

1. Check what extensions your ROMs use
2. Go to System Settings > Extensions
3. Add the correct extensions (e.g., .zip, .bin, .md, .gen)
4. Multiple extensions? Separate with commas: .bin, .cue, .iso

Scan Subfolders Disabled If your ROMs are in subfolders:

1. Go to System Settings
2. Enable "Scan Subfolders"
3. Click "Rescan Games"

Files in Wrong Location Double-check your ROM folder:

1. Open your file manager
2. Navigate to the path you entered in HyperHQ
3. Verify ROM files are actually there
4. Make sure they're not in a subfolder (unless you enabled subfolder scanning)

Games Imported But Don't Show in HyperSpin

System Not Visible

1. Edit the system in HyperHQ
2. Check that "Show in HyperSpin" is enabled
3. Save changes
4. Restart HyperSpin

No Games Visible Maybe they're all hidden:

1. Go to the system's Games tab
2. Check the visibility toggle on games
3. Unhide the ones you want to show

HyperSpin Not Refreshing Force HyperSpin to reload:

1. Close HyperSpin completely
2. Reopen it
3. Your system should appear now

Wrong Number of Games Showing

Hidden Games Some games might be hidden:

• Toggle the "Show Hidden" filter in HyperHQ
• Unhide games you want visible

Extension Mismatch HyperHQ only imports files matching your extensions:

• Review your ROM folder
• See what file types you have
• Add missing extensions to system settings
• Rescan Games

Duplicate Files If you see doubles:

• Different versions (regions, revisions)
• Parent and clone ROMs (MAME)
• Hide duplicates you don't need

Emulators Not Launching

Game Launches But Emulator Crashes

Emulator Path Wrong

1. Go to System > Manage Emulators
2. Verify the saved executable: .exe on Windows, a native executable on Linux, or the configured Flatpak/Wine/Proton launcher.
3. Open the containing folder and confirm the file exists.
4. On Linux, check executable permission and exact filename case.
5. Reselect the correct installation and test the emulator directly.

Command-Line Parameters Wrong Different emulators need different parameters:

MAME:

%ROM%

RetroArch

Use the core path selected in the platform configuration. Windows cores end in .dll; Linux cores end in .so. Do not copy a Windows core path into a Linux launch command. See RetroArch Setup.

Standalone Emulators:

• Check the emulator's documentation
• Often just "%ROM%" works
• Some need full paths, others need just filename

ROM Format Not Supported Make sure your emulator supports the ROM format:

1. Test the ROM directly in the emulator (outside HyperSpin)
2. If it doesn't work there, the ROM might be corrupted
3. Try a different ROM file
4. Verify you have the right BIOS files (if needed)

Missing RetroArch Core If a RetroArch core file is missing, HyperHQ displays a notification:

• Message: "Missing RetroArch Core: [Core Name]" (e.g., "Missing RetroArch Core: Kronos")
• Guidance: The notification includes the expected file path and instructions to download the core via RetroArch's Online Updater
• The full expected path is shown so you know exactly where the core should be placed

To resolve:

1. Open RetroArch
2. Go to Online Updater > Core Downloader
3. Download the required core
4. Verify the matching core file appears at the reported path: .dll on Windows or .so on Linux.

RetroArch Shows Touch Controls or the Wrong Bezel If RetroArch shows its default touch-controller overlay instead of a bezel, the game probably does not have a usable game bezel or system/default bezel configured.

HyperHQ uses this order for Bezel Project overlays:

1. Game-specific bezel override in RetroArch/config/<Core>/<ROM>.cfg
2. System/default bezel in RetroArch/overlays/<System Default>.cfg
3. Per-game disable failsafe if no usable bezel exists

To resolve:

1. Re-download bezels for the system from HyperHQ.
2. Make sure the ROM filename matches the Bezel Project filename. Console packs usually expect No-Intro style names; MAME packs usually expect MAME short names.
3. Check that the matching overlay exists under RetroArch/overlays/GameBezels/<System>/ or RetroArch/overlays/ArcadeBezels/.
4. Check that the system/default overlay exists at the root of RetroArch/overlays/.
5. In RetroArch settings, confirm Video Overlay is enabled unless you intentionally disabled overlays for that game or system.

See Managing Media: Bezels for the full bezel layout.

Missing BIOS Files Many emulators need BIOS files:

• PlayStation needs BIOS files in the emulator folder
• Dreamcast needs boot ROMs
• Check your emulator's documentation for requirements
• Place BIOS files in the correct folders

Nothing Happens When Launching

Emulator Not Configured

1. Check that you've selected an emulator for this system
2. Go to System Settings > Default Emulator
3. Choose an emulator from the dropdown
4. If list is empty, add an emulator first

Scripts Blocking Launch If you have pre-launch scripts:

1. Disable them temporarily
2. Try launching again
3. If it works, the script has an issue
4. Check the script for errors

Permission issues

1. Confirm your normal user has access to the emulator, ROM, BIOS, and save locations.
2. On Windows, review folder access and any scoped repair prompt.
3. On Linux, check executable permission, mount options, and Flatpak folder access.
4. Retry the same game and review the launch log.

Game Closes Immediately After Launch

Force Terminate Issues If a game or emulator hangs and you force-close it, HyperHQ shows a notification confirming the action. If games keep closing:

1. Check the logs for error messages during launch
2. Verify the ROM file isn't corrupted
3. Test the emulator with a different game
4. Check BIOS files are in place (if required)

Disc-Based Games (CUE/BIN) For PlayStation, Saturn, and other disc-based systems:

• Make sure the .cue file is selected as the launch file
• Verify .bin files are in the same folder as the .cue
• Check filenames match what's in the .cue file
• HyperHQ now handles CUE/BIN selection automatically

Check the Logs

Settings > View Logs shows exactly what's failing:

• Look for error messages when you try to launch
• Common errors explain missing files or wrong paths
• Copy error messages when asking for help

Media Not Displaying

System or Game Logos Not Showing in HyperSpin

Files in Wrong Folder System and game logos go in specific locations:

HyperSpin/Media/[System Name]/Wheel/

Check that:

1. The folder exists
2. Files are actually there
3. Folder name matches system name exactly (case-sensitive!)

File Names Don't Match Game logo files must match ROM names exactly:

• ROM: street_fighter.zip
• Game logo: street_fighter.png
• Even spacing and capitalization must match

Wrong File Format HyperSpin prefers PNG for system and game logos:

• Convert JPG/BMP files to PNG
• Make sure transparency is preserved
• Check file isn't corrupted (open it in image viewer)

HyperSpin Needs Restart Media doesn't always hot-reload:

1. Close HyperSpin
2. Reopen it
3. Media should appear now

Backgrounds Not Loading

Same Naming Rules Apply Background files must match ROM names:

HyperSpin/Media/[System Name]/Images/[game name].png

File Size Too Large Huge images can fail to load:

• Keep backgrounds under 5MB
• Resize if needed (match your screen resolution)
• Convert to JPG if PNG is too large

Theme Override Some themes use custom backgrounds:

• Your images might be there but theme isn't showing them
• Try a different theme
• Check theme settings in HyperSpin

Videos Won't Play

Codec Issues HyperSpin needs proper video codecs:

1. Install K-Lite Codec Pack (basic version)
2. Restart computer
3. Try videos again

Video Format Use MP4 with H.264 encoding:

• AVI sometimes works but can be problematic
• Convert videos to MP4 if they won't play
• Keep resolution reasonable (720p or 1080p max)

File Path Too Long Check the path reported by the media error:

• Windows: Shorten the folder path if the player reports a path-length error.
• Linux: Check filename case, mount availability, and read permission.
• Shorten system names
• Rename video files to be shorter

Missing Video Plugin Make sure video playback is enabled in HyperSpin settings.

Downloads Failing

Check Login Status For HyperTheme/EmuMovies downloads:

1. Go to Settings > Accounts
2. Verify you're signed in
3. Re-authenticate if needed

Network Issues If downloads keep failing:

1. Check internet connection
2. Try downloading individual items instead of batch
3. Pause and resume download queue
4. Check Settings > View Logs for specific errors

Disk Space Make sure you have enough space:

• Videos use lots of space
• Check available disk space
• Clean up if needed

Server Issues Sometimes media servers are busy:

• Try again later
• Check HyperSpin forums for service status
• Download smaller batches instead of everything at once

Controller Configuration Problems

Controllers Not Detected

Check operating-system detection

Windows	Linux
Open Bluetooth/device settings, then test with Set up USB game controllers	Open Bluetooth/device settings, then test with your distribution's controller tool
Review the installed device driver	Review kernel support, device access, and sandbox permissions

Check HyperHQ detection

1. Open Settings, Controllers.
2. Refresh devices or restart HyperHQ after connecting the controller.
3. Reconnect the device and test its inputs.
4. Review SDL mapping if the device appears but buttons differ.

USB Hub Issues Some USB hubs cause problems:

• Connect controller directly to computer
• Try different USB ports
• Avoid unpowered USB hubs

Button Mapping Not Working

Wrong Profile Selected

1. Check active controller profile
2. Make sure you're editing the right profile
3. Save after making changes

Conflicts With Keyboard If both keyboard and controller work:

• This is normal
• You can disable keyboard input if needed
• Or just ignore it

Arcade Controls Specific For arcade encoders (IPAC, etc.):

• They appear as keyboards, not game controllers
• Map them in keyboard section instead
• Each button is a keyboard key

Controls Not Working in Games

Emulator Has Own Mapping Many emulators have their own controller settings:

1. Configure controller in the emulator itself
2. HyperSpin controls the menu, emulator controls the game
3. Check emulator documentation for controller setup

RetroArch Special Case RetroArch needs configuration:

1. Open RetroArch
2. Go to Settings > Input
3. Configure controller for each core
4. Save configuration

LED Lighting Not Working

LEDBlinky Not Connecting

LEDBlinky Installed? HyperHQ needs LEDBlinky to control lights:

1. Install LEDBlinky separately
2. Configure it for your LED setup
3. Then connect it in HyperHQ Settings

Wrong Port/Settings

1. Verify LEDBlinky works on its own
2. Test it outside HyperHQ first
3. Then connect HyperHQ to LEDBlinky

LED Hardware Not Responding Check the hardware:

• Verify LED controller is connected
• Check power supply
• Test with LEDBlinky directly
• Check wiring if DIY setup

Lights Don't Change With Games

Animation Not Configured

1. Set up LED animations in LEDBlinky
2. Map games to animation profiles
3. Enable game-specific lighting

HyperSpin Not Triggering Make sure HyperSpin integration is enabled:

• Check HyperHQ Settings > LED
• Verify "Enable LED integration" is on
• Restart HyperSpin after changes

Plugin Errors

Plugin Won't Install

Download Failed

1. Check internet connection
2. Try downloading again
3. Download plugin manually and install from file

Compatibility Issues Make sure plugin is compatible:

• Check plugin documentation
• Verify it works with your HyperHQ version
• Some plugins need specific dependencies

Permission Denied

1. Retry the install or reinstall from the plugin details.
2. Review the permission-repair prompt when HyperHQ identifies a Windows access-control failure.
3. On Windows, approve the scoped administrator prompt when repair is required.
4. On Linux, check your user access to the plugin folder, executable permission, and mount options.
5. Open Activity when the retry still fails.

Canceling permission repair makes no permission changes. HyperHQ does not apply the repair to the full HyperSpin folder.

Files Locked

1. Close the program named in Activity or the failure message.
2. Close file manager windows showing the plugin folder.
3. Retry the operation.

A locked-file failure is different from a folder permission failure and does not start permission repair.

Plugin Not Working After Install

Restart Required Many plugins need a restart:

1. Close HyperHQ completely
2. Reopen it
3. Plugin should load now

Configuration Needed Some plugins need setup:

• Check Settings > Plugins
• Look for plugin-specific settings
• Follow plugin documentation

Check Plugin Logs Settings > View Logs > Plugin Logs shows plugin-specific errors.

Plugin Crashes HyperHQ

Disable Plugin

1. Start HyperHQ in Safe Mode (hold Shift while opening)
2. Go to Settings > Plugins
3. Disable the problematic plugin
4. Restart normally

Update or Reinstall

• Use Check for Updates from the plugin menu.
• Open View Changelog before installing a release.
• Use Reinstall for a fresh marketplace copy.
• Report a repeated failure to the plugin developer with the Activity error and plugin log.

Performance Issues

HyperHQ Runs Slowly

Large Game Libraries With thousands of games:

• Use search instead of scrolling
• Hide games you don't play
• Performance is normal with 10,000+ games, but UI may be slower

Low System Resources Check computer performance:

1. Open Task Manager on Windows or your Linux system monitor
2. Check CPU and RAM usage
3. Close other programs
4. Restart computer if it's been running for days

Database Issues If HyperHQ gets slower over time:

1. Go to Settings > Database
2. Click "Optimize Database"
3. This rebuilds indexes and speeds things up

Startup Media Checks If HyperHQ feels busy right after opening on a large library, go to Settings > General and turn Scan Media on HyperHQ Startup off.

That only skips routine startup media verification and background default-theme checks. Manual media downloads, per-system refreshes, and targeted scans still run when you start them.

HyperSpin Laggy With Lots of Game Logos

Video Causing Lag Videos use lots of resources:

• Lower video quality in settings
• Disable videos if they're too much
• Reduce video resolution (720p instead of 1080p)

Too Many Visible Games Hide games you don't play:

• Keep wheel to 100-200 games
• Hide duplicates and clones
• Use collections to organize

Texture Memory HyperSpin loads system and game logos into memory:

• Reduce logo image sizes
• Use consistent image sizes
• Restart HyperSpin periodically

Slow Media Downloads

Server Load Media servers can be busy:

• Download during off-peak hours
• Be patient with large downloads
• Download systems one at a time

Bandwidth Throttling Check if your connection is throttled:

• Close other downloads/streaming
• Pause cloud sync services
• Check with your ISP

Database Issues

Database Corruption

Symptoms

• Games disappear randomly
• Systems won't load
• HyperHQ crashes on startup
• Error messages about database

Recovery Steps

1. Close HyperHQ
2. Go to Settings > Database > Backup & Restore
3. Restore from latest backup
4. If no backup exists, click "Repair Database"

Prevent Corruption

• Don't force-close HyperHQ (let it exit properly)
• Regular backups (Settings > Database > Create Backup)
• Keep backups on different drive

Lost Game Data

Restore From Backup If you have backups:

1. Settings > Database > Backup & Restore
2. Select backup date
3. Click Restore
4. Confirm (this overwrites current database)

No Backup Available If you don't have backups:

• Rescan ROM folders to reimport games
• Metadata will be lost (you'll need to re-enter it)
• Media should still be in folders
• Set up automatic backups going forward

Import/Export Issues

Export Fails If database export crashes:

• Try exporting one system at a time
• Check disk space
• Use XML format (smaller files)

Import Doesn't Work When importing databases:

• Verify file isn't corrupted
• Check it's the right format (XML or JSON)
• Try smaller imports
• Check logs for specific error

Log Files and Debugging

Finding Logs

Open Settings, HyperHQ, Logs to locate the active log folder on Windows or Linux. The current application derives logs from its installed layout. Do not assume an AppData location.

For database and profile locations, use Data and Reinstall.

Types of Logs

• Application Log: General HyperHQ errors and info
• System Log: System and emulator launch info
• Plugin Log: Plugin-specific messages
• Download Log: Media download status

Reading Log Files

Understanding Errors Look for lines with "ERROR" or "EXCEPTION". A Windows example:

ERROR: Could not find emulator at path: C:\Emulators\mame.exe

On Linux, the missing path might refer to /home/chris/Emulators/mame. Check the exact executable path reported by your log.

Common Log Messages

"File not found"

• A path is wrong somewhere
• Check the file path in the error
• Verify the file exists

"Access denied"

• Permission issue
• Check access for your normal user
• Review folder ownership and permissions; on Linux, also check mount and sandbox access

"Could not connect"

• Network issue
• Check internet connection
• Verify login credentials

"Database error"

• Database might be corrupted
• Try repair or restore from backup

Using Logs for Support

When asking for help:

1. Reproduce the problem
2. Check logs for error messages
3. Copy the relevant error lines
4. Include them when asking for help
5. Be specific about what you were doing when it happened

Reset Procedures

Resetting HyperHQ Settings

Soft Reset (Keep your data)

1. Settings > General
2. Click "Reset to Defaults"
3. Confirms - this only resets settings, not data

Reinstall with a backup

1. Create a database backup and copy the HyperSpin library, emulator saves, and external data to separate storage.
2. Close ecosystem apps and uninstall HyperHQ through the matching package flow.
3. Preserve library and user data unless your intended reset requires removing them.
4. Reinstall the matching Windows or Linux package.
5. Select your library root and restore through Settings, Database Backup.

The active user profile normally lives in %USERPROFILE%/.HyperHQ/ on Windows or ~/.HyperHQ/ on Linux. HYPERHQ_DATA_DIR overrides this location. See Data and Reinstall before removing profile files.

Resetting a System

Remove and Re-add

1. Back up your media first (it won't be deleted but just in case)
2. Delete the system in HyperHQ
3. Add it again
4. Rescan Games
5. Media should still be there

Rescan Games If games are wrong but system is OK:

1. System Settings > Games tab
2. Click "Clear All Games"
3. Click "Rescan Games"
4. Fresh import from your ROM folder

Resetting Database

Clear Everything

1. Settings > Database
2. Click "Clear Database"
3. Confirm (this deletes EVERYTHING)
4. You'll need to set up systems again

Start Over Clean If nothing else works:

1. Export any systems you want to keep
2. Clear database
3. Run setup wizard again
4. Import exported systems
5. Rebuild from there

FAQ

Why don't my custom logos or videos show after I copy them into the media folders?

Use the override folders for custom media instead of replacing files in the managed media cache. HyperHQ keeps downloaded media in its own managed folders, so HyperSpin does not pick up files copied into folders such as media/[system]/logo system or media/[system]/video snaps reliably.

Put custom files in the matching override folder instead. For example:

• Game videos: Media/[System]/Video/
• Game logos: Media/[System]/Wheel/
• System logos: Media/MainMenu/Wheel/

After adding override media, rebuild the cache in HyperHQ. HyperHQ should then detect the override media automatically and HyperSpin will use it before falling back to the regular media.

For the full folder layout and naming rules, see Media Overrides.

Getting Help

Community Forums

HyperSpin-fe.com The official community is super helpful:

• Search for your issue first (probably solved already)
• Post in the appropriate section
• Provide details (HyperHQ version, what you tried, error logs)
• Be patient - volunteers help when they can

What to Include When Asking

• What you're trying to do
• What's happening instead
• What you've already tried
• Error messages from logs
• Your operating system/version, architecture, package version, and hardware

Documentation

Check Other Guides Often your answer is in another section:

• Getting Started - Initial setup
• Managing Systems - System configuration
• Working With Games - Game library issues
• Managing Media - Artwork and video problems
• Media Overrides - Custom artwork and video overrides

Search the Docs Use your browser's Find feature (Ctrl+F) to search for keywords across all guides.

Support Resources

Official Website HyperSpin-fe.com has:

• Downloads
• Forums
• Wiki
• Official announcements

Discord Real-time help from community members:

• Faster than forums
• Share screenshots easily
• Get help from experienced users

YouTube Video tutorials for visual learners:

• Setup walkthroughs
• Configuration guides
• Common issue fixes

Reporting Bugs

Is It Actually a Bug?

Before reporting, make sure:

• You've tried the troubleshooting steps above
• It happens consistently (can you reproduce it?)
• It's not user error (we've all been there)
• Logs show it's a real error, not a configuration issue

How to Report

Gather Information

1. What version of HyperHQ are you using?
2. What were you doing when it happened?
3. Can you reproduce it reliably?
4. What error messages appear?
5. Relevant log excerpts

Where to Report

• GitHub Issues (if HyperHQ has a public repo)
• Official forums in Bug Reports section
• Support email (check official site)

Good Bug Reports Include

• Clear title describing the issue
• Steps to reproduce
• Expected behavior vs actual behavior
• Screenshots or videos
• Log files
• System specs (operating system/version, architecture, GPU/driver, and hardware)

Example Good Report

Title: Games fail to import when path contains special characters

Steps to reproduce:
1. Create a system with the affected ROM path. Example: C:/ROMs/Genesis (Japan) on Windows or /home/chris/ROMs/Genesis (Japan) on Linux.
2. Add .bin, .md, .gen extensions
3. Click Save
4. No games imported

Expected: Games in folder should import
Actual: Zero games show in list

Logs show: Error parsing path with parentheses
HyperHQ version: 2.0.3
OS: Windows 11 Pro x64, or the exact Linux distribution/version
Linux session: desktop/version, X11 or Wayland, Desktop or Gaming Mode

Feature Requests

Have an idea to make HyperHQ better?

• Post in Feature Requests forum section
• Explain the use case (why it's useful)
• Describe how it would work
• Check if someone already suggested it (upvote instead!)

Still Stuck?

If you've tried everything and it's still not working:

1. Take a Break - Fresh eyes help
2. Start Over - Sometimes a clean slate is fastest
3. Ask for Help - The community wants you to succeed
4. Be Patient - Complex setups take time to dial in

Remember: Everyone struggles with setup at first. You're not alone, and it WILL work. The HyperSpin community has helped thousands of people get their arcade running, and they'll help you too.

Quick Reference

Common File Locations

Content	Windows	Linux
HyperHQ data	%USERPROFILE%/.HyperHQ/	~/.HyperHQ/
Database backups	%USERPROFILE%/.HyperHQ/backups/	~/.HyperHQ/backups/
Default HyperSpin root	C:/ProgramData/HyperSpin/	~/HyperSpin/
Logs	Open Settings, HyperHQ, Logs	Open Settings, HyperHQ, Logs

Use the configured paths for custom installs. HYPERHQ_DATA_DIR overrides the profile root. Linux setup defaults to ~/HyperSpin/ regardless of XDG_DATA_HOME. Enable hidden files to see .HyperHQ.

Key Settings Locations

• View Logs: Settings > View Logs
• Database: Settings > Database
• Accounts: Settings > Accounts
• Plugins: Settings > Plugins
• Controllers: Settings > Controllers
• Media Settings: Settings > Media

Emergency Commands

Safe Mode Hold Shift while launching HyperHQ (disables plugins)

Reset Settings Settings > General > Reset to Defaults

Repair Database Settings > Database > Repair Database

Force Rescan System > Games tab > Rescan Games

Final Thoughts

Most issues are simple misconfigurations, not broken software. Check paths, verify files exist, read the logs, and you'll usually find the answer.

The HyperSpin community is incredibly helpful. Don't hesitate to ask questions - chances are someone has already solved your exact issue.

And remember: Building the perfect arcade setup is a journey. Take it one step at a time, celebrate small wins, and before you know it, you'll have an amazing setup that makes you smile every time you turn it on.

Happy gaming!