Skip to main content

Troubleshooting

This page is for installer maintainers. For end-user install, launch, and reinstall issues, see User troubleshooting.

Building​

Could not find install4jc​

The build scripts couldn't locate the compiler. Install install4j, or set the path explicitly:

export INSTALL4JC=/path/to/install4jc

See the detection order.

The build fails on signing​

For a quick local build, skip signing entirely:

./build-all.sh --no-installer-signing        # all platforms, unsigned
./build-mac-local.sh --faster                 # mac only, always unsigned

If you want signed media, make sure the password environment variables are exported (WIN_KEYSTORE_PASSWORD, MAC_KEYSTORE_PASSWORD, APPLE_ID_PASSWORD) and, for Windows, that the YubiKey is inserted and keys/certchain/ exists.

--test didn't produce a DMG​

That's expected — --test is a dry run that compile-checks the project without copying the final artifact or launching it. Drop --test to get a real DMG.

Paths break on a fresh clone​

DeepPhe-and-Launcher.install4j contains some local absolute paths (payloads, signing files). Update them in install4j — or make them relative — before building on a new machine. See Repo layout.

Installing (end users)​

The installer seems stuck "Downloading…"​

The installer fetches ~50–110 MB payloads from GitHub during installation. It needs network access; on a slow link this stage takes a while. See Install flow.

Windows: "the directory path must not contain a space"​

An external pipeline dependency can't tolerate spaces in the install path. Choose a no-space location such as C:\DeepPhe (the installer suggests one).

The pipeline won't start on Java 26​

The installer patches the NLP run scripts with the required module options (--add-exports / --add-opens). If you run the scripts from an older install that predates this patch, re-run the installer or add those options manually. See the configure step.

Signing the release assets​

Wrong jsign alias​

If signing fails on the alias, run the jsign command without --alias; it prints the available aliases. Slot 9a shows as X.509 Certificate for PIV Authentication.

A signed .exe won't launch​

Authenticode adds a cert table to the same PE overlay these bundles use for their payload, which occasionally breaks it. Smoke-test each signed binary on Windows once. If a download the installer verifies has a checksum, regenerate it after signing. See Signing Windows assets.

Documentation site​

Run the docs locally​

cd website
npm install
npm start

Requires Node 18+ (Docusaurus 3). Build the static site with npm run build.