Troubleshooting

Most Nucleus pipelines work the first time. The ones below are the recurring incidents: notarization, Microsoft Store identity, corporate CAs, GraalVM reflection, Wayland-on-NVIDIA. Each entry follows the same shape.

macOS notarization fails with "The signature does not include a secure timestamp"

Symptom. xcrun notarytool submit returns Invalid with a status detail mentioning a missing or invalid timestamp.

Cause. Code signing ran without --timestamp, or your machine couldn't reach Apple's timestamp server at sign time.

Fix. Nucleus signs with --options runtime --timestamp by default. If you wrote a custom codesign step (e.g. for lipo-merged universal binaries outside the build-macos-universal action), add --timestamp and re-sign. Check xcrun codesign -dv --verbose=4 <Your.app> and look for Timestamp=….

macOS notarization fails with "The signature does not include a hardened runtime"

Symptom. Status: Invalid, log mentions hardened runtime.

Cause. Custom codesign step missing --options runtime.

Fix. Add --options runtime to every codesign invocation. The default Nucleus pipeline does this — only custom CI scripts trip here.

Microsoft Store: "MinVersion <= 10.0.17134.0"

Symptom. Partner Center rejects the upload:

Package acceptance validation error: bundle is not valid. You can't upload msix/msixbundle/msixupload packages that target Windows with a MinVersion <= 10.0.17134.0.

Cause. No explicit minVersion set in appx { }. The default falls back to 10.0.14316.0, which is below the Store's floor.

Fix.

appx {
    minVersion = "10.0.17763.0"        // Windows 10 1809
    maxVersionTested = "10.0.22621.0"  // Windows 11 22H2
}

Microsoft Store rejects publisher / identity

Symptom. Upload validation fails with an identity mismatch.

Cause. identityName, publisher, or publisherDisplayName don't match Partner Center's reservation.

Fix. Copy the exact values from Partner Center → Product identity. publisher is CN=<GUID> issued by the Store, not your local signing cert's CN. See Windows targets.

SSLHandshakeException on a corporate network

Symptom. HTTPS calls from the app fail with SSLHandshakeException: PKIX path building failed.

Cause. A corporate proxy / VPN gateway is MITM-ing TLS with a private root CA the JDK trust store doesn't know.

Fix. Two options, complementary:

1. Build time — ship the CA inside the bundled JDK's cacerts:

   nativeDistributions {
       trustedCertificates.from(files("certs/corp-ca.pem"))
   }

   See trusted certificates.

2. Runtime — use the OS-native trust store via native-ssl:

   implementation("dev.nucleusframework:nucleus.native-ssl:2.0.0")
   implementation("dev.nucleusframework:nucleus.native-http:2.0.0")

   Inject NativeHttpClient.create() into your HTTP client (works with java.net.http, OkHttp, Ktor).

Auto-update fails: "no matching file" on macOS

Symptom. UpdateResult.Failed(NoMatchingFileException) on macOS after a check.

Cause. The release only contains a .dmg. macOS auto-update uses ZIP.

Fix. Add TargetFormat.Zip next to TargetFormat.Dmg. Both go in the same release; latest-mac.yml references both. See the callout in auto-update.

GraalVM Native Image: ClassNotFound / NoSuchMethod at runtime

Symptom. App runs fine on JVM but crashes under native-image with reflection errors or missing methods.

Cause. GraalVM is closed-world. Reflection, resources, dynamic proxies need to be registered ahead of time.

Fix. The Nucleus plugin ships GraalVM Reachability Metadata for itself plus FileKit and other common libraries (see automatic metadata). For your own code:

1. Run with -agentlib:native-image-agent=config-output-dir=... on a representative workload.
2. Commit the generated reachability-metadata.json next to META-INF/native-image/....

For unsupported libraries, see GraalVM configuration.

AppImage: 60-second cold start

Symptom. App opens fine in dev but takes a full minute when packaged as AppImage.

Cause. compressionLevel = CompressionLevel.Maximum. AppImage uses squashfs; max compression triggers FUSE decompression on every launch.

Fix. Use CompressionLevel.Normal (default) for production. Maximum is for archival.

DEB / RPM packaging fails: "Please specify project homepage"

Symptom. packageDeb or packageGraalvmDeb fails immediately.

Cause. Unlike jpackage, electron-builder requires homepage for DEB.

Fix.

nativeDistributions {
    homepage = "https://myapp.example.com"
}

Wayland on NVIDIA: black window, garbled rendering

Symptom. Compose UI renders incorrectly under Wayland on NVIDIA drivers.

Cause. NVIDIA's GBM / EGLstream history with Wayland is rocky; Compose Desktop on AWT/JBR fights it.

Fix. Switch to the Tao backend — decorated-window-tao renders via native Skia surfaces on Wayland without going through AWT. If you must stay on AWT, set WLR_NO_HARDWARE_CURSORS=1 or run under XWayland.

Unresolved reference 'JewelDecoratedWindow' after migrating to 2.0

Symptom. Import is correct, IDE shows the function, but compilation fails.

Cause. In 2.0 the composable is an extension on NucleusApplicationScope. A wrapper composable you wrote in 1.x doesn't propagate the receiver.

Fix. Make your wrapper an extension too:

fun NucleusApplicationScope.MyOnboardingWindow(...) {
    JewelDecoratedWindow(...) { /* content */ }
}

See migrate from 1.x → Step 4.

NoClassDefFoundError: DecoratedDialogKt on Tao

Symptom. Dialog crashes on Tao but works on AWT.

Cause. You're calling the AWT-only JewelDecoratedDialog (no receiver) under NucleusBackend.Tao.

Fix. Switch the host composable to an extension on NucleusApplicationScope so the call resolves to NucleusApplicationScope.JewelDecoratedDialog, which dispatches per backend.

Dependency resolution is looking for a library compatible with JVM runtime version 11

Symptom. Gradle fails on the Jewel artifact.

Cause. Toolchain not bumped to 25.

Fix.

kotlin { jvmToolchain(25) }

See migrate from 1.x → Prerequisites.

Flatpak packaging task silently skips

Symptom. packageFlatpak reports "skipped" with no error.

Cause. flatpak-builder or the org.freedesktop.Platform//23.08 runtime is missing on the build host.

Fix.

sudo apt-get install -y flatpak flatpak-builder
flatpak remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo
flatpak install -y flathub org.freedesktop.Platform//23.08
flatpak install -y flathub org.freedesktop.Sdk//23.08

In CI, use setup-nucleus with flatpak: 'true'.

Snap packaging fails with snapcraft: command not found

Symptom. packageSnap fails before producing anything.

Cause. Missing snapd / snapcraft on the build host.

Fix.

sudo apt-get install -y snapd
sudo snap install snapcraft --classic

Or in CI, setup-nucleus with snap: 'true'.

Need more?

If you hit something not listed here, check:

• Packaging cluster for per-OS specifics.
• Performance cluster for GraalVM and AOT details.
• The migration guides for namespace/scope errors after upgrading.