fix(engine): actionable errors when the legacy backend can't start#187
Merged
Conversation
,#120) macOS users hit cryptic failures ("Server failed to start", "Empty response: rustledger-ffi-wasi") because the *legacy* JSON-RPC backend spawns a `wasmtime` CLI subprocess that macOS Gatekeeper blocks. The real fix is the in-process component backend, now the default (#183) — these reports predate that release. Make the remaining failure modes actionable rather than cryptic: - The "Empty response" error now explains the subprocess/Gatekeeper cause and points at the component backend. - The "wasmtime CLI not found" error explains the component backend needs no external binary. - `get_engine` no longer silently falls back from the unavailable component backend to the JSON-RPC engine (which needs a `wasmtime` CLI binary users don't have, producing exactly those cryptic errors). It falls back only if the CLI is actually present, else raises a clear "reinstall rustfava" error. This doesn't change the default path; it just makes the legacy/fallback path fail with guidance. The substantive fix for the reporters is shipping the component default in a release. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This was referenced Jun 19, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Improves the failure UX behind #136 / #120 (macOS "Server failed to start" / "Empty response: rustledger-ffi-wasi").
Root cause (for the record)
Those reports are from the legacy JSON-RPC backend, which spawns a
wasmtimeCLI subprocess — and macOS Gatekeeper blocks the bundled binary (the reporter even had toxattr -d com.apple.quarantine). The substantive fix already exists: the in-process component backend is now the default (#183, no subprocess). Those reports predate that release, so the real resolution is shipping it — see the issue comments.What this PR does (the remaining sharp edges)
Makes the legacy / fallback path fail with guidance instead of cryptically:
get_enginefallback footgun fixed: when the component backend is unavailable it no longer silently falls back to the JSON-RPC engine (which needs awasmtimeCLI binary users don't have — producing exactly those cryptic errors). It falls back only if the CLI is actually present, else raises a clear "reinstall rustfava" error.Default path unchanged. Verified: component is still selected by default; the blocked-component fallback raises the actionable error; engine + component tests pass (25); mypy clean; zero new lint (engine.py's pre-existing E501 debt is untouched — that crate is slated for removal in rustledger#1419).