Troubleshooting

This page covers common issues players may encounter and how to resolve them.

ℹ️ Note: If your issue isn't listed here, please open a support ticket on our Discord server.

Patcher Issues

Patcher won't launch

Cause: Missing .NET 8 Desktop Runtime

Solution:

1. Download and install .NET 8 Desktop Runtime from Microsoft
2. Restart the patcher

"Windows protected your PC" warning

Cause: Windows SmartScreen doesn't recognize the patcher because it's new software

Solution:

1. Click "More info"
2. Click "Run anyway"

This is safe — our patcher is not malicious.

Patcher won't connect / Stuck at patching

Possible causes and solutions:

1. Firewall blocking the connection
   • Add the HymnRO Patcher to your firewall's exception list
   • Temporarily disable your firewall to test
2. Antivirus interference
   • Add the HymnRO folder to your antivirus exclusions
   • Common culprits: Avast, McAfee, Windows Defender
3. Corrupted download
   • Delete the HymnRO folder and re-download from the downloads page

Patcher shows errors while downloading files

Solution:

1. Close the patcher
2. Re-open and let it retry
3. If the issue persists, try downloading at a different time (server may be busy)

Game Client Issues

Game won't start / Closes immediately

First-time players:

1. Make sure you clicked SETUP in the patcher first
2. Configure your resolution settings
3. Then launch the game

If it still doesn't work:

1. Right-click the game executable → Properties → Compatibility
2. Check "Run as administrator"
3. Try checking "Run in compatibility mode for Windows 7"

Black screen after launching

Possible causes and solutions:

1. Resolution issue
   • Run SETUP and try a lower resolution
   • Try switching between Fullscreen and Windowed mode
2. Graphics driver issue
   • Update your graphics drivers from the manufacturer's website (NVIDIA, AMD, Intel)
3. DirectX issue
   • Install/repair DirectX from Microsoft

Game crashes randomly

Common solutions:

1. Close background applications
   • Discord overlay can cause crashes — try closing Discord completely
   • Logitech G Hub has been known to cause issues
   • Close any screen recording or streaming software
2. Disable overlays
   • Turn off NVIDIA GeForce Experience overlay
   • Disable Steam overlay (if applicable)
   • Disable Discord overlay
3. Run as administrator
   • Right-click the game → Properties → Compatibility → "Run as administrator"
4. Disable fullscreen optimizations
   • Right-click the game → Properties → Compatibility → "Disable fullscreen optimizations"

"Failed to connect to server"

Possible causes and solutions:

1. Server maintenance
   • Check our Discord for announcements
2. Firewall/Antivirus blocking
   • Add the game to your firewall exceptions
   • Whitelist the HymnRO folder in your antivirus
3. Internet connection issue
   • Restart your router
   • Try a different network if possible

"Disconnected from server" after character select

Possible causes and solutions:

1. Unstable internet connection
   • Check your connection stability
   • Try using a wired connection instead of WiFi
2. VPN interference
   • If using a VPN, try disabling it
   • Some VPNs can cause connection issues

Game freezes but doesn't crash

Solution:

1. Press Alt+Tab to switch to another window, then switch back
2. If that doesn't work, press Alt+F4 to close the game
3. As a last resort, open Task Manager (Ctrl+Shift+Esc) and end the process

Performance Issues

Game is laggy / Low FPS

Solutions:

1. Lower graphics settings
   • Run SETUP and reduce resolution
   • Enable "Reduced graphics" options if available
2. Close background applications
   • Close unnecessary programs, especially browsers with many tabs
3. Update graphics drivers
   • Download latest drivers from your GPU manufacturer

High ping / Network lag

Note: Our server is hosted in Germany. Players far from Europe may experience higher latency.

Solutions:

1. Use a wired connection instead of WiFi
2. Close bandwidth-heavy applications (streaming, downloads, etc.)
3. Try a gaming VPN that has servers closer to Germany (may help for some players)

Linux Support

⚠️ Warning: Linux support is experimental and not officially supported. These instructions are community-provided.

The HymnRO Patcher is built with WebView2 and is Windows-only. However, the game client itself can be run on Linux using Wine or Lutris.

Running on Linux with Lutris

Prerequisites:

• Lutris installed
• Wine dependencies installed for your distro

Missing Dependencies

Issue: Linux does not have all dependencies installed by default. In particular, dotnet desktop runtime may not be present.

Solution:

• Install dependencies using Winetricks, or
• Unzip the binary files to the correct directory in the Wine prefix
• Default location: /home/[username]/Games/umu/umu-default/

Note: .NET Desktop Runtime does not have a native Linux version — it installs to the Wine prefix only, not to Linux itself.

Patcher doesn't render (blank blue screen)

Issue: When running through Lutris, the patcher displays entirely blue and never renders. Lutris may become unresponsive.

Explanation: This is likely caused by Wayland display servers. Distros using Wayland instead of X11 or XWayland may experience this issue.

Current status: No known solution at this time. As X11 is being phased out, workarounds may need to be developed.

Workaround: You may be able to patch on a Windows machine (or VM) and copy the patched files to Linux.

Game closes immediately when launched through Lutris

Issue: Setting the game executable in Lutris causes it to close immediately upon launch.

Solution: In the Lutris game configuration, add the launch argument: 1rag1

Explanation: The game client expects an SSO login token from the patcher. The 1rag1 argument bypasses this and allows access to the regular login system.

"Incorrect user ID or Password" after bypassing SSO

Issue: After using the 1rag1 argument, login attempts return "Incorrect user ID or Password."

Current status: Under investigation.

Possible workarounds being explored:

• Running the Python login script inside a Winetricks instance
• Using Wine instead of Proton
• Other methods to force Proton compatibility

Still Having Issues?

If none of the above solutions work:

1. Take a screenshot of any error messages
2. Note what you were doing when the issue occurred
3. Open a support ticket on our Discord server
4. Provide as much detail as possible — this helps us help you faster!

See Also

• Get Started — Installation guide
• FAQ — Frequently asked questions
• Commands — List of available commands