Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/retired64/sm64coopdx_launcher/llms.txt

Use this file to discover all available pages before exploring further.

When something goes wrong, the launcher displays the error message as red text beneath the logo on the main screen. Most failures fall into one of five categories: the game binary cannot be found, a language file is missing from the installation, no valid ROM was located, SDL2 cannot initialize, or the save directory is not writable. The quick-reference table below maps each error to its root cause and the fastest fix, followed by detailed accordion sections for each category.

​
Quick reference

ErrorCauseSolution
Game binary not found: {path}Binary path unresolved through all 5 tiersSet SM64COOPDX_PATH or configure launcher.toml
Language file not found: {path}Incomplete game installationRe-extract the full game archive
No valid Super Mario 64 US ROM found.ROM absent or wrong MD5 hashPlace baserom.us.z64 in the game directory
Savepath {path} is not writable: {err}Insufficient file permissionschmod -R u+rw ~/.local/share/sm64coopdx/

​
Game binary errors

The launcher resolves the sm64coopdx binary through five tiers in order. If a tier points to a non-existent file the launcher falls through to the next one automatically. When every tier is exhausted and no file is found, spawn_game returns:
Game binary not found: /path/to/sm64coopdx
The error is displayed as red text on the launcher screen.Resolution tiers (highest to lowest priority)
  1. --game-path CLI argument
  2. SM64COOPDX_PATH environment variable
  3. Per-profile game_path field in profile.json
  4. launcher.toml → [game].path
  5. Automatic search: <launcher_dir>/../games/mario64/sm64coopdx, then ./sm64coopdx, ../sm64coopdx, and finally any ~/sm64coopdx_Linux-*/sm64coopdx directory
Step-by-step fixes
1

Check whether the binary exists

Locate your extracted SM64 Coop DX release folder and confirm the binary is present:
ls -l ~/sm64coopdx_Linux-*/sm64coopdx
2

Set the environment variable (quick fix)

Export SM64COOPDX_PATH before launching:
export SM64COOPDX_PATH="/home/$USER/sm64coopdx_Linux-1.5.1/sm64coopdx"
./sm64coopdx-launcher
3

Use the --game-path flag

Pass the path directly on the command line for a one-off launch:
./sm64coopdx-launcher --game-path /path/to/sm64coopdx
4

Configure launcher.toml (persistent fix)

Create or edit ~/.config/sm64coopdx/launcher.toml:
[game]
path = "/home/YOUR_USER/sm64coopdx_Linux-1.5.1/sm64coopdx"
5

Verify execute permissions

If the binary exists but cannot be spawned, it may not be marked executable:
chmod +x /path/to/sm64coopdx
The launcher also attempts to set 0o755 automatically on Unix, but doing it manually guarantees the fix.
All resolved paths are canonicalized to an absolute form (symlinks resolved) before the game is spawned. If your binary lives behind a symlink, the launcher follows it correctly.

​
ROM errors

Before launching the game, the launcher searches for a .z64 file whose MD5 hash exactly matches the Super Mario 64 US ROM. If no matching file is found across all search locations the launch is aborted with the following error (rendered in red on the launcher screen):
No valid Super Mario 64 US ROM found.
Expected MD5: 20b854b239203baf6c961b850a4a51a2
Place 'baserom.us.z64' in one of these locations:
- /path/to/game/dir
- /home/user/.local/share/sm64coopdx
Or set [game].rom_path in ~/.config/sm64coopdx/launcher.toml
Expected MD5: 20b854b239203baf6c961b850a4a51a2Search order
  1. The game binary’s directory
  2. ~/.local/share/sm64coopdx/
  3. [game].rom_path in launcher.toml
  4. Any ~/sm64coopdx_Linux-*/ directory in your home folder
FixesPlace your ROM in the game directory and verify its hash:
md5sum "Super Mario 64 (USA).z64"
# Expected: 20b854b239203baf6c961b850a4a51a2
If the hash does not match, your ROM dump is not the supported US v1.0 revision. Only this specific revision is accepted.To point the launcher to a ROM in a non-standard location, add a rom_path entry to ~/.config/sm64coopdx/launcher.toml:
[game]
rom_path = "/path/to/Super Mario 64 (USA).z64"
Once the launcher finds a valid ROM, it copies it to ~/.local/share/sm64coopdx/baserom.us.z64 and reuses that copy on subsequent launches (skipping the copy step if the file is already present and valid).
Do not rename the ROM to baserom.us.z64 yourself and place it in the save directory while the launcher is running — the launcher validates by MD5, not filename, so a corrupt or wrong-region file with the right name will still be rejected.
This screen appears when the game process starts but cannot read the ROM from the save directory. The most common cause is that the ROM copy step succeeded but the resulting file at ~/.local/share/sm64coopdx/baserom.us.z64 is not readable by the game process.Check write and read permissions on the save directory:
ls -la ~/.local/share/sm64coopdx/baserom.us.z64
If the file is owned by root or has no read permission for your user, fix it:
chmod u+rw ~/.local/share/sm64coopdx/baserom.us.z64
If the directory itself is not writable the launcher will fail before this point, but a partial copy due to a previous interrupted launch can also cause this freeze. Delete the partial file and re-launch to trigger a fresh copy:
rm ~/.local/share/sm64coopdx/baserom.us.z64

​
Language and installation errors

After resolving the game binary path, the launcher calls validate_game_installation(), which checks that {game_dir}/lang/English.ini exists next to the binary. If this file is missing, the launch is blocked and the following error is shown in red on the launcher screen:
Language file not found: /path/to/game/lang/English.ini
The game installation seems incomplete. Make sure the 'lang/' directory
is present next to the game binary.
Cause: The game release archive was not fully extracted, or only the binary was copied without its supporting files.Fix:Re-extract the complete SM64 Coop DX release archive into a single directory:
tar -xf sm64coopdx_Linux-*.tar.gz -C ~/
# or for zip releases:
unzip sm64coopdx_Linux-*.zip -d ~/
Verify the directory structure after extraction:
ls ~/sm64coopdx_Linux-*/lang/English.ini
The lang/ folder must be a sibling of the sm64coopdx binary. Moving the binary to another location without moving the lang/ folder alongside it will reproduce this error.
The launcher also checks for a dynos/ directory at the same level. While its absence only triggers a warning rather than an error, missing DynOS packs means texture and character packs will not load.

​
Asset errors

The launcher itself is built on SDL2 and requires several SDL2 libraries to be installed on your system. A missing library causes an immediate crash before any UI is drawn, often with an error like libSDL2.so.0: cannot open shared object file.Required system libraries
# Debian / Ubuntu
sudo apt install libsdl2-2.0-0 libsdl2-image-2.0-0 libsdl2-mixer-2.0-0 libsdl2-ttf-2.0-0

# Arch Linux
sudo pacman -S sdl2 sdl2_image sdl2_mixer sdl2_ttf

# Fedora
sudo dnf install SDL2 SDL2_image SDL2_mixer SDL2_ttf
Launcher asset filesAfter confirming the libraries are present, the launcher also requires its own asset bundle to be installed under ~/.local/share/sm64coopdx/assets/. The most critical file is the font:
~/.local/share/sm64coopdx/assets/fonts/SuperMario256.ttf
If the assets directory is missing, copy it from alongside the launcher binary:
mkdir -p ~/.local/share/sm64coopdx/assets
cp -r /path/to/launcher/assets/* ~/.local/share/sm64coopdx/assets/
Full asset tree (from config.rs)
AssetPath under ~/.local/share/sm64coopdx/assets/
Fontfonts/SuperMario256.ttf
Splash screensplash.png
Vinyl disc graphicvinyl_disc.png
Logosm64coopdx/logo.png
Window iconsm64coopdx/icon.png
Backgroundbackground.png
Navigation soundsounds/navigation_sound.wav
Splash soundsounds/splash_sound.wav
Music directoryogg-sounds/
Mod databasedatabase_sm64coopdx.json
The launcher does not currently auto-install assets on first run. If any asset is missing the SDL2 texture load will silently fail or produce a crash depending on which file is absent.

​
Permission errors

Before spawning the game, validate_game_installation() writes a temporary probe file (.launcher_write_test) to the save directory to confirm it is writable. If this write fails, the error is shown in red on the launcher screen and the launch is cancelled:
Savepath /home/user/.local/share/sm64coopdx is not writable: permission denied
If the save directory does not yet exist, the launcher attempts to create it first via fs::create_dir_all. If that creation fails, a separate error is shown:
Cannot create savepath /home/user/.local/share/sm64coopdx: permission denied
Fix — restore user ownership and write permissions:
chmod -R u+rw ~/.local/share/sm64coopdx/
If the directory is owned by root (for example after a previous sudo run), reclaim ownership first:
sudo chown -R "$USER":"$USER" ~/.local/share/sm64coopdx/
chmod -R u+rw ~/.local/share/sm64coopdx/
If the directory does not exist yet and the parent path (~/.local/share/) is not writable, this points to a broader home-directory permission problem that must be resolved at the filesystem level.
The game process is spawned with a clean, whitelisted environment (no LD_PRELOAD, no LD_LIBRARY_PATH). Permission errors in the save directory are always a filesystem issue, not an environment one.

Build docs developers (and LLMs) love

Get started for freeTalk to us