fix: raise a clear error when the wasmtime native lib is missing libgcc - #160
fix: raise a clear error when the wasmtime native lib is missing libgcc#160qw-in wants to merge 1 commit into
Conversation
wasmtime-py's bundled native library needs libgcc_s.so.1, which most distros ship by default but Alpine Linux does not. Previously this surfaced as a raw ctypes OSError several frames deep, with no indication of the actual fix. Now arcjet._local catches that specific OSError signature on import and re-raises a clear ArcjetRuntimeError pointing at `apk add libgcc`. Any other OSError (a different missing library, permissions, etc.) is left untouched so we don't misdiagnose unrelated failures. Verified in Docker (astral/uv:python3.10-alpine): fails with the new clear error before `apk add libgcc`, imports cleanly after. Fixes #159.
![arcjet-review[bot]](https://avatars.githubusercontent.com/u/24397786?s=60&v=4){kind=small}
There was a problem hiding this comment.
Arcjet Review — 🟢 Low Risk
Decision: Approved
Rationale: Small, well-scoped change that adds a new ArcjetRuntimeError exception and wraps the wasmtime-dependent imports in try/except to translate a specific known OSError (missing libgcc) into a clearer, actionable error message. Unrelated OSErrors are passed through unchanged, avoiding misdiagnosis. The change is covered by three new unit tests verifying both translation and pass-through behavior. No security-sensitive surface area is touched; the error message contains no secrets or user-controlled data, and the substring match is on the exception text only.
Summary of Changes
Adds an ArcjetRuntimeError exception and wraps arcjet._analyze imports so that a wasmtime native-library load failure caused by a missing libgcc (common on Alpine) is re-raised with an actionable message pointing at apk add libgcc. Other OSErrors are passed through unchanged. Includes unit tests for the translation helper.
Notes
Diff is well under the 1000-line size threshold. No escalation triggers fired. Security review checklist applied: no auth, injection, secrets, crypto, or data-protection concerns; error message is static text plus the original exception string (no user input).
Review: 03488761 | Model: anthropic/claude-opus-4-7 | Powered by Arcjet Review
| ) | ||
| except OSError as exc: | ||
| raise _translate_wasmtime_import_error(exc) from exc | ||
|
|
There was a problem hiding this comment.
Consider whether OSError is narrow enough here. The wrapped import block pulls in arcjet._analyze, which may itself raise other OSErrors (e.g. a file-not-found while loading a WASM blob, or unrelated I/O during module init) that aren't actually about wasmtime's native lib. The _translate_wasmtime_import_error helper already passes those through unchanged, so behavior is safe — but the surrounding comment/intent suggests this except is specifically for wasmtime. Worth a brief comment clarifying that the narrowing happens inside the helper, or alternatively catching at a tighter scope around just the wasmtime-triggering import.
| if _MISSING_LIBGCC_SIGNATURE in str(exc): | ||
| return ArcjetRuntimeError( | ||
| "Arcjet's local WebAssembly runtime (wasmtime) could not load " | ||
| "because `libgcc` is missing. Most Linux distributions include " |
There was a problem hiding this comment.
Nit: the signature match is case-sensitive substring against str(exc). If a future wasmtime/loader version formats the message differently (e.g. uppercase, or routes through repr), this will silently stop translating. Consider matching case-insensitively, or matching on just libgcc plus an indicator like wasmtime to be a bit more robust — at the cost of a slightly broader match. Current behavior is defensible; flagging only as a future-proofing consideration.
There was a problem hiding this comment.
Pull request overview
This PR improves the developer experience when Arcjet’s local WASM runtime (wasmtime) fails to import on Alpine Linux due to a missing libgcc_s.so.1, by translating that specific OSError into a clearer Arcjet-specific runtime error and adding focused tests for the translation behavior.
Changes:
- Add
_translate_wasmtime_import_error()inarcjet._localto map the known missing-libgccimport failure to anArcjetRuntimeErrorwith actionable guidance. - Introduce
ArcjetRuntimeErroras a new SDK error type for native runtime dependency load failures. - Add unit tests validating that only the known
libgccsignature is translated and otherOSErrors pass through unchanged.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.
| File | Description |
|---|---|
src/arcjet/_local.py |
Adds import-time translation of the specific wasmtime missing-libgcc OSError into a clearer ArcjetRuntimeError. |
src/arcjet/_errors.py |
Introduces ArcjetRuntimeError for runtime/native dependency failures. |
tests/test_local.py |
Adds test coverage for the new wasmtime-import error translation helper. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| except OSError as exc: | ||
| raise _translate_wasmtime_import_error(exc) from exc |
Proposed solution for #159 but not sure its a good idea/worth it!
wasmtime-py's bundled native library needs libgcc_s.so.1, which most distros ship by default but Alpine Linux does not. Previously this surfaced as a raw ctypes OSError several frames deep, with no indication of the actual fix.
Now arcjet._local catches that specific OSError signature on import and re-raises a clear ArcjetRuntimeError pointing at
apk add libgcc. Any other OSError (a different missing library, permissions, etc.) is left untouched so we don't misdiagnose unrelated failures.Verified in Docker (astral/uv:python3.10-alpine): fails with the new clear error before
apk add libgcc, imports cleanly after.Fixes #159.