blog · · engineering

Both ways outl dies on open happen before any of my code runs

OUTL-4 is a fatal panic on Windows: `Failed to setup app: runtime error: Could not find the webview runtime, make sure it is installed`. Tauri raises it from setup when `webview_version()` fails, so the guard has to sit in `run()` before the builder exists, and it has to copy Tauri's own predicate exactly: the gate is `is_ok()`, which means an `Ok("")` is a machine Tauri will happily start and the stricter, more obviously correct check is the regression. Android has the same bug one layer lower, in the static initializer of wry's generated `Rust` object, where the error arrives as an `ExceptionInInitializerError` out of `super.onCreate`. Both guards run upstream of the crash reporter, which means the failure class that motivated the reporter is now the one class it will never file.

A
9 min read

OUTL-4 is a fatal panic on Windows x86_64, from desktop@0.13.0-beta.265: Failed to setup app: runtime error: Could not find the webview runtime, make sure it is installed.

I did not write that sentence and neither did anything in outl. Tauri raises it from setup, the process dies there, and the panic is the crash report. That report is the only reason I know the failure exists, because I own no PC without WebView2 on it.

The fix for it makes sure that report never arrives again. Android has the same bug one layer lower and the same answer, which is why these are one subject and not two.

the failure is in Tauri’s setup, so the guard cannot be in mine

tauri::webview_version() is Result<String, tauri::Error>, documented as “Get WebView/Webkit version on current platform”. tauri-runtime-wry 2.12.1, the version in this lockfile, records wry::webview_version().is_ok() as whether a runtime is installed. On Windows a false becomes Error::WebviewRuntimeNotInstalled, whose Display is the string above, and App::run wraps it as Failed to setup app: {e} and panics.

That sequence runs while the main window is created. There is no setup hook early enough to stand in front of it, no builder callback that fires first, and nothing of mine on the stack at all. The only place left is before the builder exists, which is the first statements of run() in crates/outl-desktop/src-tauri/src/lib.rs:

ignore_sigpipe();

// Windows only, before the crash reporter. A failed `webview_version()`
// is the setup panic; here it is a message and an exit.
#[cfg(windows)]
webview_boot::exit_if_runtime_missing(tauri::webview_version().map_err(|err| err.to_string()));

let _telemetry = outl_telemetry::init("desktop", outl_config::telemetry_enabled());

Three lines in order, and the order is the design. ignore_sigpipe is the one that already had to be first, for the closed stderr that turned a log line into an abort. The WebView2 question goes between it and outl_telemetry::init, and I will come back to why that gap is where the whole cost of this change lives.

The map_err(|err| err.to_string()) is not decoration. The decision function takes Result<String, String>, so it never names tauri::Error, which is what lets all four of its tests run on Linux where there is no WebView2 and no Windows to simulate.

the installer already handles this, and it names the three cases it does not

outl’s NSIS installer uses Tauri’s default bundle.windows.webviewInstallMode, which is downloadBootstrapper. docs/getting-started.md has said so for a while, in the same table that already promised a Windows ARM64 installer the pipeline was not building:

The installer downloads Microsoft’s WebView2 bootstrapper when the runtime is not already there. That download needs a network, and it does not run again if the runtime is removed later or the program is started without the installer.

So the installer covers the common case and misses three: a machine that was offline when the bootstrapper ran, a runtime removed or broken afterwards, and an executable started without ever going through the installer. OUTL-4 came off one of those three, and I cannot tell which from the report.

The obvious alternative is offlineInstaller, which embeds the standalone runtime in the setup .exe. It fixes the first case and neither of the other two: a runtime removed in March is still removed, and a binary that never met the installer never met the embedded copy either. It also adds about a hundred megabytes to a download for every user who already has the runtime. The install mode stays at Tauri’s default, and the boot check covers what no install mode can.

an empty version string starts the app, because the stricter check is the regression

The decision is five lines in crates/outl-desktop/src-tauri/src/webview_boot.rs:

pub(crate) fn webview_boot(version: Result<String, String>) -> WebviewBoot {
    match version {
        Ok(_) => WebviewBoot::Continue,
        Err(_) => WebviewBoot::Exit {
            code: MISSING_RUNTIME_EXIT_CODE,
            message: missing_runtime_message(),
        },
    }
}

The Ok(_) is the load-bearing part, and it is the part that looks sloppy. A version string is there to be read. The tempting version of this function parses it, or at minimum refuses an empty one, because Ok("") is obviously not a working runtime and refusing it is obviously more correct.

It is not more correct. It is a different question. Tauri’s gate is is_ok(), and is_ok() is what decides whether a window gets created. A machine that returns Ok("") is a machine Tauri will start. Refusing it means outl shows a download page to somebody whose app was about to work, and the user has no way to discover that, because the process they would debug exited before it drew anything.

The error’s text gets the same treatment, which is why it is Err(_) and not a match on the message. Tauri does not consult that string either. Two readings of one Result is how two answers drift, and the drift is invisible until a Windows user reports an app that refuses to start on a PC where the previous build was fine.

Four tests pin it, and the one that matters is the one that looks like it is asserting a bug:

/// Tauri's gate is `is_ok()`. An empty `Ok` is not the panic this
/// module exists to stop, and refusing it would be a second opinion.
#[test]
fn an_empty_version_string_still_starts_the_app() {
    let decision = webview_boot(Ok(String::new()));
    assert_eq!(decision, WebviewBoot::Continue);
}

Its sibling any_probe_error_is_a_missing_runtime covers the other direction with Err(String::new()), so an error with no text is still an exit. Stub the decision so every probe continues and two of the four fail, which is the check that the test file is testing anything at all: cargo test -p outl-desktop --lib webview_boot reports 2 passed; 2 failed, with a missing runtime must not start the app as the message. With the real decision in place the crate is 53 passed; 0 failed.

macOS and Linux never call any of this. A failed WebKit probe on macOS is not a missing runtime, and Tauri still creates the webview there, so running the same check would be a new failure mode invented by the guard against failure modes.

a release build has no console, so the answer has to be a window

main.rs carries #![cfg_attr(not(debug_assertions), windows_subsystem = "windows")]. A release build launched from Explorer has no console, so a message printed to stderr is a message nobody receives. The exit path writes to both:

#[cfg(windows)]
fn tell_and_exit(message: &str, code: i32) -> ! {
    use std::io::Write;
    // Same writer as the tracing subscriber: a closed stderr must not turn
    // this exit into `failed printing to stderr`.
    let _ = writeln!(outl_telemetry::lossy_stderr(), "{message}");
    show_message_box(message);
    std::process::exit(code);
}

show_message_box is a direct MessageBoxW with a null owner window, because at that point in run() the process genuinely has no window to own the dialog. The text names the Evergreen runtime and Microsoft’s download page, which is the same URL Tauri’s own dialog names, and the test asserts the message does not contain the word panic. The exit status is 1.

lossy_stderr is there for the terminal launch, and it is the writer from the crash reporter post, the one that reports a broken pipe as a finished write. An exit path that panics on its own goodbye message would be a funny way to fix a crash on startup.

Android fails one layer lower, in an initializer nobody calls

The same shape, worse ergonomics. On Android the app died on open for every device that refused liboutl_mobile_lib.so: 16 KB-page phones up to v0.12.0-beta.226, where dlopen rejects a library whose LOAD segments are aligned to 4 KB, and any device whose ABI the APK does not carry.

The alignment itself was fixed separately, with -Wl,-z,max-page-size=16384 in .cargo/config.toml for both 64-bit Android targets, zipalign -P 16, and a script that reads the finished APK back and fails the job, in the same spirit as opening every published file instead of trusting the step that produced it. Reading the beta.226 APK is what settled the diagnosis: the two vendored AAR libraries carried p_align 0x4000 and ours carried 0x1000.

The crash itself is a JVM class-initialization fact. Tauri’s generated Rust object calls System.loadLibrary from a static initializer, and a static initializer that throws does not throw at that line. The JVM wraps it in ExceptionInInitializerError and raises it at whatever first touches the class, and every later touch is a NoClassDefFoundError. For MainActivity the touching line is super.onCreate. So the failure arrives inside the framework’s startup, uncaught, before any of my code has a say, exactly as it does on Windows.

OutlNativeLibrary is the one place that asks:

val loadError: Throwable? by lazy {
  try {
    System.loadLibrary(NAME)
    null
  } catch (e: LinkageError) {
    report(e)
    e
  } catch (e: RuntimeException) {
    report(e)
    e
  }
}

by lazy is synchronized, so a share target and a worker racing in a cold process still load once, and System.loadLibrary is idempotent per class loader, so a successful probe makes the later loads in Rust, NativeSetup and NativeSync no-ops rather than second attempts. LinkageError is the 16 KB and missing-ABI cases; RuntimeException catches a SecurityException from a locked-down ROM. An OutOfMemoryError is deliberately not caught, because it is not a fact about the library.

report writes one logcat line under the outl tag with everything a bug report needs:

adb logcat -s outl
# E outl: native library liboutl_mobile_lib.so did not load: abis=[arm64-v8a] pageSize=16384 sdk=35 ...

16384 next to a load error is the beta.226 failure exactly. Three entry points ask before touching Rust: MainActivity hands over to NativeLoadErrorActivity, the share target says Nothing to save., and SyncWorker returns Result.failure() without reaching NativeSync. The error screen is a plain AppCompatActivity with its views built in code, never a TauriActivity, because wry and Tauri call into the failed library from every lifecycle hook. It is 124 lines, not exported, and shows the ABI, the page size, the Android version, the device, the app version and the error as selectable text, next to a link to the issue tracker.

Its first sentence is about the thing a user is actually afraid of when an app refuses to open: “outl could not load its native library on this device, so it stopped before opening anything. Your notes were not opened or changed.”

super before Rust, which is an assumption about wry 0.57 and nothing else

Android requires super.onCreate. The library that super.onCreate reaches is the one that just failed. So MainActivity calls it and catches what it throws:

val loadError = OutlNativeLibrary.loadError
if (loadError != null) {
  nativeUnavailable = true
  startActivity(NativeLoadErrorActivity.intent(this, loadError))
  try {
    super.onCreate(savedInstanceState)
  } catch (expected: LinkageError) {
  }
  finish()
  return
}

That is only safe because of an ordering inside somebody else’s code. Activity.onCreate runs first in the chain, so the part Android checks for has happened by the time wry’s WryActivity.onCreate calls Rust.onCreate and the initializer throws. Calling finish() from onCreate then goes straight to onDestroy, skipping onStart, onResume, onPause and onStop, which are the other hooks where wry calls Rust. onDestroy catches the same LinkageError for the same reason.

This is a dependency on wry calling super before Rust, and nothing in the repository fails if that stops being true. It is true of wry 0.57. docs/android-platform.md says to re-read WryActivity.kt when bumping it, and a doc line is a weaker guarantee than a test. I do not have a better one: the behaviour only exists on a device, PR CI does not build Android at all, and the Robolectric test I ran locally on API 34 is not committed because this module has no unit test setup in CI.

the exit cannot be a crash report, and that is the price

Go back to the ordering in run(). The WebView2 check is deliberately above outl_telemetry::init, which means the reporter is not running on this path, which means a PC with no WebView2 now produces nothing at all: no event, no count, no version breakdown. crates/outl-telemetry/CLAUDE.md records why in one sentence, and it is the sentence I find hardest to like: the reporter is not started there “because the failure it replaces is the setup panic Sentry was filing”.

Android gets there by accident rather than by choice, and ends up stricter. outl_telemetry::init is the second statement of mobile’s run(), and run() lives inside liboutl_mobile_lib.so. A device that refuses the library never reaches the reporter, because the reporter is in the library. A crash report cannot tell you that the thing containing the crash reporter would not load.

Which inverts the reason this reporter exists. The Android app that closed on open is the failure that motivated adding crash reporting in the first place, and it is the one class of failure crash reporting structurally cannot deliver. The replacement on each platform is a human: a Windows message box naming a download, an Android screen naming the ABI and the page size with the issue tracker under it. Both need somebody to care enough to type.

The rest of what this does not cover is the ordinary kind. Nothing here was run on a Windows PC that actually lacks WebView2, because I do not have one; cargo check -p outl-desktop --target x86_64-pc-windows-msvc does not reach this crate on my machine, since aws-lc-sys fails first on a missing windows.h, so the Win32 call was compiled on its own against that target with rustc --emit=metadata and clippy-driver, and the Windows desktop CI job is the first build with a real SDK. The claim that Sentry stores nothing for that exit is a claim about code I can read, not a thing I have watched happen.

The lesson is not that pre-flight checks are good. It is that a guard installed upstream of your own entry point is not your code’s guard, it is the framework’s, and it inherits the framework’s predicate including the parts that look too lenient to keep. Copy is_ok() and you refuse exactly the machines Tauri would have refused. Improve on it and you have written a second opinion whose disagreements all land on users you will never hear from, because the whole point of the thing is that it exits before anything can report.

The Windows half is outl PR #415, in crates/outl-desktop/src-tauri/src/webview_boot.rs. The Android half is outl PR #381, in gen/android/app/src/main/java/app/outl/mobile_app/.