Troubleshooting

This guide covers common problems you may encounter with An Anime Game Launcher and their solutions.

Installation Issues

Dependencies not found

Required packages:

git - Version control and repository access
p7zip or 7z - Archive extraction
libwebp / dwebp - Image processing

Check installation:

which git
which 7z || which 7za
which dwebp

Install missing packages:Arch Linux:

sudo pacman -Syu git p7zip libwebp-utils

Debian/Ubuntu:

sudo apt install git p7zip-full webp

Fedora:

sudo dnf install git p7zip libwebp-tools

The package name for libwebp on Arch was fixed in version 3.18.0 (previously showed incorrect package name).

Launcher won't start

Check these items:

Verify installation
- Flatpak: flatpak list | grep anime
- AUR: pacman -Q | grep anime-game
- Ensure package is actually installed
Check permissions
```
ls -la ~/.local/share/anime-game-launcher/
```
Launcher needs read/write access to its folder
Review logs
- Flatpak: flatpak run moe.launcher.an-anime-game-launcher
- Terminal output shows startup errors
Dependencies
- GTK4 libraries installed
- libadwaita available
- Graphics drivers up to date

If using Flatpak, make sure you have the required Flatpak runtimes installed: flatpak install flathub org.gnome.Platform//46

First-run wizard doesn't appear

This happens when:

First-run marker file already exists
Configuration file present from previous installation

Force first-run:

rm ~/.local/share/anime-game-launcher/config.json
rm ~/.local/share/anime-game-launcher/.first-run

Then restart the launcher.

The first-run file is removed at src/ui/first_run/download_components.rs:597 after successful setup.

Download Problems

Downloads fail or timeout

Common causes:

Network connectivity issues
Slow/unstable connection
Server-side problems
Firewall blocking connections

Solutions:

Increase timeout
```
export LAUNCHER_REQUESTS_TIMEOUT=16000
```
Default is 8000ms (8 seconds), increased from 3000ms in version 3.7.0.
Reduce Sophon threads
- Settings > General > Sophon Threads
- Lower to 2-4 threads on slow connections
- Higher threads = more concurrent downloads = more bandwidth

Check network

ping google.com
curl -I https://github.com

Proxy support Set environment variables:

export http_proxy=http://proxy:port
export https_proxy=http://proxy:port

Proxy support added in version 3.7.0.

The launcher uses minreq for HTTP requests with configurable timeout via LAUNCHER_REQUESTS_TIMEOUT environment variable.

Download stuck at 100%

Fixed in version 3.15.3If on older version:

Update launcher to 3.15.3 or later
Wait 5-10 minutes (may be verifying)
Check console output for errors

If on current version:

Download is likely applying patches
Check progress bar status text
Monitor CPU usage (should be active)
Wait for “Removing outdated files” stage

Do not force-kill the launcher during “Applying patches” or “Removing outdated files” stages. This can corrupt your installation.

Download restarts in endless loop

Fixed in version 3.15.5Symptoms:

Reaches 100%
Immediately restarts from 0%
Repeats continuously

Solution: Update to launcher version 3.15.5 or later.Workaround for older versions:

Clear temp folder downloads

rm -rf ~/.local/share/anime-game-launcher/temp/updating-*

Restart launcher
Begin download again

Insufficient disk space

Space requirements:

Game download: ~20-40 GB
Unpacked game: ~40-80 GB
Temp folder: ~20-40 GB during updates
Voice packs: ~2-4 GB each

Total recommendation: Minimum 100 GB free spaceCheck free space:

df -h ~/.local/share/anime-game-launcher
df -h /tmp

Free up space:

Remove old Wine builds (Settings > Enhancements)
Remove old DXVK builds
Clear temp folder
Disable unused voice packs
Use game repair to clean up

The launcher performs free space checks (added in version 3.9.2) with symlink resolution before starting downloads.

Segmented archive extraction fails

Support added in version 3.9.1Requirements:

7z or 7za binary installed
Sufficient disk space (2x archive size)
All segments downloaded

Verify 7z:

which 7z || which 7za
7z --help

Check temp folder: Look for all archive parts:

ls -lh ~/.local/share/anime-game-launcher/temp/updating-*/

Should see: archive.zip.001, archive.zip.002, etc.If extraction fails:

Verify all parts are present
Check file permissions
Manually test extraction:
```
7z x archive.zip.001
```

Game Launch Issues

Game won't start

Check launcher state:

Wine not installed
- Launcher shows “Download Wine” button
- Go to Settings > Enhancements
- Select and download a Wine version
Prefix not created
- Launcher shows “Create Prefix” button
- Click it to initialize Wine prefix
- Wait for completion (2-5 minutes)
DXVK not installed
- Launcher shows “Install DXVK” button
- Download and apply DXVK
- Required for DirectX to Vulkan translation
Game not installed
- Launcher shows “Download” or “Install”
- Download the game first

The launcher performs a check for broken DXVK installations (added in version 3.17.0).

FPS Unlocker not working

Fixed in version 3.17.0Check these:

FPS Unlocker enabled
- Settings > Enhancements > FPS Unlocker
- Toggle should be ON
Correct runner compatibility
- Version 3.17.0 fixed compatibility with some runners
- Update launcher if on older version
FPS Unlocker version
- Updated to 1.2.1 in version 3.15.5
- BAT script updated for latest Wine behavior
Custom FPS Unlocker
- Version 3.9.4 replaced FPS unlocker with custom implementation
- Should work more reliably

Logs: Check game logs for FPS unlocker messages:

tail -f ~/.local/share/anime-game-launcher/game.log

Game crashes on launch

Common causes:

Telemetry not disabled
- Some game versions require telemetry to be disabled
- Launcher should prompt automatically
- Manually: Menu > Disable Telemetry
Wrong Wine version
- Try different Wine version
- Wine-GE recommended for best compatibility
- Settings > Enhancements > Wine Version
Missing DXVK
- Reinstall DXVK
- Settings > Enhancements > Reinstall DXVK
Corrupted prefix
- Backup and recreate Wine prefix
- Settings > Wine > Prefix
Game files corrupted
- Use game repair function
- Menu > Repair Game Installation

Check logs:

# Game output
cat ~/.local/share/anime-game-launcher/game.log

# Wine errors
tail -f ~/.wine/drive_c/users/$(whoami)/Temp/wine-debug.log

Game logs are written to game.log (added in version 3.10.2). Size is controlled by LAUNCHER_GAME_LOG_FILE_LIMIT environment variable.

Game runs but no audio

Solutions:

Check voice pack installed
- Settings > General > Game Voiceovers
- Enable desired language
- Download voice pack

PulseAudio/PipeWire

# Check audio system
pactl info

# Test audio
speaker-test -c 2

Wine audio configuration
- Settings > Wine Tools > Wine Configuration
- Audio tab > Test Sound
- Select correct audio driver
Sandbox issue
- Game sandboxing may break audio
- Settings > Sandbox > Disable sandbox
- Audio issues with sandbox noted in version 3.6.0

Sandboxed game running has known audio issues (see changelog 3.6.0: “Fixed sandboxed game running (sounds are broken for now)”).

Game runs on wrong display (multi-monitor)

Gamescope solutions:

Enable Gamescope
- Settings > Gamescope > Enable Gamescope
- Select output display
- Configure resolution
Force grab cursor
- Settings > Gamescope > Force grab cursor
- Added in version 3.9.5
- Keeps game on correct display

Without Gamescope:

Move game window manually
Configure Wine virtual desktop
Use window manager rules

Gamescope settings were reworked in version 3.12.0 with improved configuration options.

Update Problems

Failed to find game diff

Fixed in version 3.15.6Solutions:

Update launcher
- Install version 3.15.6 or later
Verify game path
- Settings > General > Game Path
- Check path exists and is correct
Check .version file
```
cat ~/.local/share/anime-game-launcher/Game/.version
```
File should exist and contain version number
Repair game
- Menu > Repair Game Installation
- Verifies all files and version

The launcher respects root .version file for game version parsing (added in version 3.11.0) and prioritizes parsed version over API response.

Predownload issues

Multiple fixes in 3.15.x versions:Progress bar not showing (3.15.2):

Update launcher
Restart predownload

Stuck on wait condition (3.15.2):

Multiple threads getting stuck
Fixed in 3.15.2

Voice pack data deleted (3.15.2):

Updating game after preload deleted voice data
Fixed in 3.15.2

Not using temp folder (3.15.1):

Preload ignored configured temp folder
Fixed in 3.15.1

Check preload status:

ls -la ~/.local/share/anime-game-launcher/temp/updating-*/.predownloadcomplete

Patch applying fails

hdiff patches:Requirements:

Sufficient disk space
Correct source files
Valid patch files

Check errors:

Console shows patch error details
May indicate corrupted download
Or incorrect game version

Solutions:

Clear partial downloads

rm -rf ~/.local/share/anime-game-launcher/temp/updating-*

Re-download
- Restart launcher
- Begin update again
Repair game first
- Menu > Repair Game Installation
- Ensures base files are correct
- Then retry update
Check voiceover migration
- Version 3.4.0 includes automatic 3.5 → 3.6 voiceover migration
- Base game hdiff errors may be caused by voiceover file conflicts
- Fixed in version 3.4.1

Do not manually edit or move game files during patch application. This will cause checksum mismatches.

Configuration Issues

Settings not saving

Check these:

File permissions

ls -la ~/.local/share/anime-game-launcher/config.json

File must be writable

Disk space

df -h ~/.local/share/anime-game-launcher

Need space to write config

JSON validity

cat ~/.local/share/anime-game-launcher/config.json | python -m json.tool

Config must be valid JSON

Flatpak permissions

flatpak override --user --filesystem=home moe.launcher.an-anime-game-launcher

Backup config:

cp ~/.local/share/anime-game-launcher/config.json ~/config.json.backup

Custom launcher folder

Using LAUNCHER_FOLDER variable:Added in version 3.6.0, you can specify custom root path.Set variable:

export LAUNCHER_FOLDER="/path/to/custom/folder"

Persistent setting: Add to ~/.bashrc or ~/.zshrc:

echo 'export LAUNCHER_FOLDER="/path/to/custom/folder"' >> ~/.bashrc

Flatpak:

flatpak override --user --env=LAUNCHER_FOLDER="/path/to/folder" moe.launcher.an-anime-game-launcher

This is useful for keeping launcher files on a different drive or partition.

Components index issues

Default index: https://github.com/an-anime-team/componentsChina users: GitHub is blocked in China. You need to:

Mirror repository
- Fork components repository
- Host on accessible platform
- Replace GitHub URLs with mirrors
Update index path
- Settings > General > Components Index
- Point to your mirror

Update config

{
  "components": {
    "path": "https://your-mirror.com/components"
  }
}

See README.md lines 66-74 for detailed China version support information.

Performance Issues

Low FPS

Optimization steps:

Enable FPS Unlocker
- Settings > Enhancements > FPS Unlocker
- Unlocks 60 FPS cap
- Custom unlocker since version 3.9.4
FSR (FidelityFX Super Resolution)
- Settings > Gamescope > FSR
- Select quality mode (Ultra/Quality/Balanced/Performance)
- Quality mode setting added in 3.7.0
Gamescope optimizations
- Enable Gamescope
- Set appropriate resolution
- Enable integer scaling if needed
- NIS (NVIDIA Image Scaling) option available

Graphics drivers

# Check driver version
vulkaninfo | grep "Driver Version"

# Test Vulkan
vulkaninfo

DXVK version
- Try different DXVK versions
- Newer isn’t always better for all GPUs
- Settings > Enhancements > DXVK Version

Integer scaling, FSR, and NIS were moved to a separate group in version 3.1.0 for better organization.

High RAM usage

Fixed in version 3.14.1Improvements:

Improved RAM usage in files MD5 hash verifier
Fixed RAM filling with buffered game logs (3.10.3)

Current optimizations:

Game log limits
```
export LAUNCHER_GAME_LOG_FILE_LIMIT=10485760  # 10MB
```
Default limit prevents log file overfilling (added 3.10.2)
Reduce Sophon threads
- Settings > General > Sophon Threads
- Fewer threads = less RAM per thread
Close other applications
- Free up system RAM
- Wine can be memory-intensive

Increase swap

# Check current swap
free -h

# Consider adding swap file if needed

Slow downloads

Optimization:

Increase Sophon threads
- Settings > General > Sophon Threads
- Try 8-16 threads for fast connections
- Default is 4 threads
Change temp folder
- Use SSD instead of HDD
- Settings > General > Temp Folder
- Faster disk = faster extraction

Network speed

# Test download speed
speedtest-cli

# Check if throttled

Server location
- Download speed depends on game servers
- Usually mirrors in multiple regions
- Peak times may be slower

Launcher-Specific Issues

Background image not updating

Fixed in version 3.0.1Check settings:

Settings > Appearance > Update Background
Toggle must be enabled

Background processing:

Changed in version 3.10.0
Improved processing in 3.10.1
Uses dwebp for image re-coding

Manual update:

rm ~/.local/share/anime-game-launcher/background*

Restart launcher to re-download.

Background picture processing logic was changed in version 3.10.2, and error handling for dwebp re-coding was added in 3.10.1.

Titlebar behavior issues

Fixed in version 3.1.0Desktop environment specific:

Some DEs don’t respect GTK4 titlebar hints
Fixed for major DEs in 3.1.0

Workarounds:

Use client-side decorations
Configure DE window rules
Use Gamescope for window management

Discord RPC not working

Removed in version 3.13.0Discord RPC feature was removed from the launcher.Previous issues (if on old version):

Fixed updates in 3.10.3
Icon selection added in 3.7.1
Icons updating added in 3.7.3

Alternative: No built-in Discord integration in current versions.

Proton support removed

Removed in version 3.16.0Official statement: “Removed support for launching with Proton from the launcher. Launching with proton externally is unaffected.”Using Proton externally: You can still use Proton, but must launch outside the launcher.Previous Proton issues:

Fixed sandbox compatibility (3.7.0)
Fixed wine tools with Proton builds (3.6.0)
Improved compatibility (3.2.0)

Getting Help

Console Output

Always check console output for detailed errors: Flatpak:

flatpak run moe.launcher.an-anime-game-launcher

Terminal:

anime-game-launcher

Look for:

Error messages in red
Warning messages
Stack traces
Network errors

Log Files

Game logs:

~/.local/share/anime-game-launcher/game.log

Launcher folder:

~/.local/share/anime-game-launcher/

Community Support

Discord server: All project life happens in the Discord server (see README.md:20). Report issues:

Contact developers directly in Discord
Provide console output
Include launcher version
Describe steps to reproduce

Wiki: GitHub Wiki contains FAQ and guides.

Version Information

Check launcher version:

Open Settings
Click “About”
Shows launcher version, core version, SDK version

Important for bug reports:

Launcher version
Distribution
Installation method (Flatpak/AUR/RPM)
Game version

First Run Setup

Initial configuration guide

Updating Games

Download and update procedures

Voice Packs

Voice pack management

GitHub Wiki

Official wiki and FAQ

Get Started

Core Features

Guides

Configuration

Installation Issues

Download Problems

Game Launch Issues

Update Problems

Configuration Issues

Performance Issues

Launcher-Specific Issues

Getting Help

Console Output

Log Files

Community Support

Version Information

First Run Setup

Updating Games

Voice Packs

GitHub Wiki

Build docs developers (and LLMs) love

Get Started

Core Features

Guides

Configuration

​Installation Issues

​Download Problems

​Game Launch Issues

​Update Problems

​Configuration Issues

​Performance Issues

​Launcher-Specific Issues

​Getting Help

​Console Output

​Log Files

​Community Support

​Version Information

​Related Resources

First Run Setup

Updating Games

Voice Packs

GitHub Wiki

Build docs developers (and LLMs) love

Installation Issues

Download Problems

Game Launch Issues

Update Problems

Configuration Issues

Performance Issues

Launcher-Specific Issues

Getting Help

Console Output

Log Files

Community Support

Version Information

Related Resources