Skip to content

Troubleshooting

Jump to bottom
Finnegan's Owner edited this page Feb 28, 2026 · 4 revisions

Troubleshooting

macOS: "Launcher can't be opened because Apple cannot check it for malicious software"

The app is not code-signed with an Apple Developer certificate. To open it:

Option 1: Right-click the app → Open → click Open in the dialog.

Option 2: Run in Terminal:

xattr -cr /Applications/Launcher.app

Java Not Found

If Launcher cannot find Java:

  1. Ensure JRE/JDK 8 or higher is installed
  2. Set JAVA_HOME environment variable, or
  3. Set the Java Home path manually in each connection's settings

On macOS, Launcher auto-detects Java via /usr/libexec/java_home. On other platforms, it relies on the JAVA_HOME environment variable.

Launch Hangs or Fails Silently

  • Check the connection address is correct (must include protocol and port, e.g., https://myserver:8443)
  • Verify the server is reachable (check the status indicator on the main screen)
  • Try disabling "Verify JAR files" in the connection options to rule out signature verification issues
  • Enable "Show Java Console" to see the administrator's stdout output

Certificate Trust Issues

If you see repeated certificate trust prompts:

  • Trusted certificates are stored in ~/.launcher/launcher-trusted-certs.json
  • If the server's certificate has changed (renewed, re-issued), you will be prompted again
  • Clicking "Trust" saves the certificate permanently

Server Shows as Unavailable (Red Dot)

The status check makes a quick HTTP request to /api/system/info. Common causes for unavailable status:

  • Server is down or unreachable
  • Firewall blocking the connection
  • Incorrect address (wrong port, missing https://)
  • Connection timeout (2 second limit)

The status check uses the same TLS settings as launch (accepts self-signed certs).

Data Migration

Launcher automatically migrates data from previous versions on first run:

Version Data Location
< 0.2.0 (Catapult) ~/catapult-data.json
0.2.0 - 1.x (Ballista) ~/.ballista/ballista-data.json
2.x+ (Launcher) ~/.launcher/launcher-data.json

Migration is automatic and non-destructive (copies, does not overwrite existing files).

Build Issues

DMG Bundling Fails on macOS

Install create-dmg:

brew install create-dmg

The .app builds successfully even without this — only the DMG packaging step requires it.

OpenSSL Errors on Windows

See Building from Source for OpenSSL setup instructions.

Cargo Build Fails

Make sure you are running from the repo root, not from src-tauri/:

# Correct
npm run tauri build

# Or for Rust-only checks
cargo check --manifest-path src-tauri/Cargo.toml

Resetting Data

To start fresh, remove the data directory:

rm -rf ~/.launcher

This removes all connections, trusted certificates, and cached JARs. Launcher will recreate the directory on next launch.

Clone this wiki locally