Skip to content

Troubleshooting

Jump to bottom
Finnegan's Owner edited this page Jun 29, 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

The administrator is a JavaFX application, so Launcher must start it with a JavaFX-enabled JDK. A plain OpenJDK will start and then fail with "JavaFX runtime components are missing".

Launcher does not auto-detect or guess a JDK. It resolves Java in this order:

  1. The connection's Java Home field, if set (<Java Home>/bin/java)
  2. Otherwise java on the system PATH

Before any download, Launcher runs a fast java -version check. If that fails, the launch is aborted with:

Java (with JavaFX) not found ... Set Java Home to a JavaFX-enabled JDK, or put one on PATH.

To fix it, install a JavaFX-enabled JDK and either set the connection's Java Home to it or put its bin directory on PATH.

Note: the java -version check only confirms a Java runtime is launchable, not that it includes JavaFX. If that check passes but the administrator window never appears and the console shows "JavaFX runtime components are missing", the resolved Java lacks JavaFX — switch Java Home to a JavaFX-enabled JDK.

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)
  • Make sure the connection's Java points to a JavaFX-enabled JDK (see Java Not Found)
  • Enable Show console in the connection options to see the administrator's stdout and stderr in a native console window

Certificate Trust Issues

Launcher pins each connection's TLS certificate on first use (trust-on-first-use). The trusted fingerprint is stored per connection as pinnedCertSha256 inside ~/.launcher/launcher-data.json — there is no separate trust-store file.

First connection — Launcher captures the server's leaf certificate and shows its SHA-256 fingerprint in a "Trust this server's certificate?" prompt. Verify the fingerprint with the server operator out-of-band before trusting; clicking Trust certificate saves it as the pin.

Certificate changed — On a later launch, if the server presents a different certificate you'll see a "This server's certificate changed" warning showing both the new fingerprint and the one you previously trusted. This is expected after a legitimate certificate renewal or re-issue. If you did not expect it, stop — a changed certificate can indicate an interception attempt. Only click Trust new certificate after confirming the change with the operator; doing so replaces the stored pin.

Server Shows as Unavailable (Red Dot)

The status check makes a quick HTTP GET to /api/system/info with a 2 second connect timeout. Common causes for unavailable status:

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

The status probe accepts self-signed certificates and ignores hostname mismatches, so it is purely a reachability check. It does not verify the certificate pin — a green dot means the server answered, not that its certificate matches what you trusted. The pin is checked separately at launch time.

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 (moves the legacy file only when no current file exists).

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

Launcher builds native-tls with vendored OpenSSL, which needs an OpenSSL build toolchain — Perl on all platforms, plus NASM on Windows. See Building from Source for 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 (including their trusted certificate pins), cached JARs, and logs. Launcher will recreate the directory on next launch.

Clone this wiki locally