Skip to content

Troubleshooting

Start with the first Oxiquill diagnostic. Generation errors include the relevant tool or path and, for authored cells, the page, fence line, cell ID when available, and exact metadata field.

A runtime-lock waiting message means another command or dev synchronization is using this project’s generated artifacts. Check the reported command, PID, host, start time, and <cacheDir>/runtime.lock path. Allow the holder to finish or stop that process normally. CLI commands wait up to 1800 seconds by default; set --lock-timeout <seconds> on build, check, docgen, clean, or test-wasm to change that limit. --lock-timeout 0 fails immediately. Watchers wait indefinitely and then synchronize the latest pending changes.

Oxiquill automatically reclaims a lock only when its host matches the current host and its PID no longer exists. A live PID, a permission-denied PID probe, or an old timestamp does not make the lock stale. Long release Wasm builds keep their locks.

An unreadable/malformed record or a record from another host is treated as an unknown owner. If no Oxiquill process is running against this project, remove the exact lock path printed in the diagnostic, then rerun the command. Check other hosts too when the project resides on shared storage. Never remove a lock while a build or synchronization is active. Lock coordination applies to one consumer project; separate projects sharing output directories are not coordinated.

Interactive cell sources changed after runtime generation started. means a cell or Rust helper input changed while the production build was running. The diagnostic lists every added, removed, or changed cell and helper path, including changed cell fields such as source or inputs.

Finish saving the sources, then rerun oxiquill build. Oxiquill does not retry automatically. A failed generation preserves the previous complete runtime; a successful build uses matching cell manifests, MDX, and Wasm. Prose-only edits keep the same generation and reuse cached runtime artifacts.

In development, a cell that is not generated yet reports that the runtime watcher will regenerate it. Allow that generation to finish; production consistency checkpoints do not run in the dev server.

SymptomResolution
Node version or syntax errorInstall Node.js 24 or newer and confirm node --version in the same shell that launches pnpm/npm.
oxiquill command not foundInstall it in project dependencies, run it through a package script, or use pnpm exec oxiquill. Do not depend on a global install.
npm/pnpm resolves source or duplicate Preact incorrectlyRemove stale node_modules, reinstall from the lockfile, and import only documented package exports. Do not deep-import package files.
Native Rollup/Vite addon cannot loadUse a normal Node build. If ghc-wasm put a static Node first in PATH, move the normal Node earlier or set OXIQUILL_NODE.
SymptomResolution
Rust toolchain/target missingInstall Rust/Cargo 1.85.0 or newer, then run rustup target add wasm32-unknown-unknown.
Rust tool download failedRestore network access, or install wasm-bindgen matching the runtime pin and Binaryen 117 wasm-opt on PATH, then rerun.
Unknown helper crateMatch crates: [...] to package.name in a direct child of the configured cratesDir. Use crates: [] when none are needed.
Stale Rust cell or missing WasmRegenerate with pnpm wasm:dev; do not edit .oxiquill or public/oxiquill.

Rust/Cargo 1.85.0 or newer is supported. Install the wasm32-unknown-unknown target. Required CI tests Rust 1.85.0; repository development uses Rust 1.99.0. Rust beta/nightly channels are accepted when their numeric version meets the minimum, but are untested. Helper crates can impose a higher Rust minimum of their own.

Oxiquill binds every module with a wasm-bindgen CLI that exactly matches the pinned runtime crate. It uses a matching binary on PATH and otherwise downloads the official prebuilt release for the host and verifies its SHA-256. Transient download failures are retried, and the same release asset is then requested through the GitHub release API. That request uses GH_TOKEN or GITHUB_TOKEN when either is set, which avoids the anonymous rate limit of shared CI runners. The token is sent only to api.github.com. Both wasm-bindgen and Binaryen wasm-opt downloads follow this policy. It never builds the CLI from source, so Rust 1.85 is sufficient. Hosts without an official prebuilt release need the matching wasm-bindgen on PATH; wasm-pack is not used.

Generated runtime dependencies keep exact pins, and every Cargo build uses --locked. Whenever the generated workspace’s dependencies change, Oxiquill seeds rust-cells/Cargo.lock from the runtime pins and from the normal and build dependency versions in each helper workspace’s own Cargo.lock (dev-dependencies are ignored), then lets Cargo resolve it once. Helper registry dependencies that no helper lock records resolve to the newest compatible version available at that time, so commit the helper workspace’s Cargo.lock or pin exactly for reproducible builds. If a helper requires a version that conflicts with Oxiquill’s exact runtime pins, resolution fails with Cargo’s error: widen the helper’s constraint to accept the pinned version, for example serde = "1" rather than serde = "=1.0.228", and rerun pnpm wasm:dev. Do not edit the generated Cargo.lock directly.

SymptomResolution
wasm32-wasi-ghc missingInstall ghc-wasm 9.14 on Linux/macOS or set OXIQUILL_HASKELL_GHC to the compiler. Native Windows generation is unsupported.
Astro/Vite fails after sourcing ghc-wasmPut a normal Node.js 24 runtime before ghc-wasm’s static Node, or set OXIQUILL_NODE.
Runtime unavailable or staleFix the compiler/cell error and rerun pnpm wasm:dev. Check the generated status diagnostic rather than editing it.
SymptomResolution
CDN or mirror request failsConfirm DNS/TLS/proxy access and the configured mirror base. The error identifies the effective URL and HTTP/connection cause.
Download times out or exhausts retriesRetry after connectivity recovers or use a complete verified cache; each attempt is limited to 30 seconds and three total attempts.
SHA-256 mismatchDo not bypass verification. Remove the named corrupt cache entry and fetch it from a trusted source/mirror.
Offline cache missPopulate the exact filename/hash on a connected machine using the same Oxiquill/Pyodide version, then transfer the verified cache.
Unsupported Python packageUse a package listed by the installed Pyodide lockfile or remove it from packages.

If different commands appear to use different directories, pass the same --config <path> and inspect the conflicting field named by the diagnostic. Relative child paths resolve against their documented parent. Do not combine Astro and paths values that normalize to different locations.

clean reports the unsafe field, its absolute resolved path, and the conflicting path role. Move the cleanup root to a dedicated generated directory when it overlaps authored input, the public root, project or repository metadata, dependencies, the framework, the persistent download cache, or another generated role. Symlink aliases do not bypass these checks.

If a custom root reports a missing or mismatched .oxiquill-ownership.json, do not manufacture the marker. Preserve or move any authored files, select a missing or empty dedicated directory, and rerun the corresponding generation or build command so Oxiquill can establish ownership. An old custom output created before ownership markers must be reviewed and emptied explicitly before it can be claimed.

Clean preflights all three targets before deleting any of them. A diagnostic for one target therefore leaves the other generated roots, authored files, repository/dependency state, and .cache/oxiquill/downloads/v1 untouched. Fix the reported configuration or ownership problem, then rerun pnpm clean.

A cell defaults to a 30,000 ms timeout. timeoutMs can select an integer from 1 through 2,147,483,647 ms, inclusive. A timeout terminates the failed language worker, rejects requests owned by it, and creates a fresh worker for later runs. Reduce the workload or choose a justified larger timeout; do not use timeout as a security sandbox.

For browser failures, verify the site was rebuilt, the expected files exist below public/oxiquill, the deployment preserves .wasm and JavaScript assets, and the configured base path matches the deployed URL. Test in a supported current Chromium, Firefox, or WebKit browser.

In the Oxiquill repository, pnpm build reuses unchanged package outputs and runtime artifacts while Astro recreates static site output. Run pnpm build:clean when source and generated output disagree: it rebuilds the package, runtimes, and site from scratch while preserving the verified download cache. In a consumer project, run oxiquill clean followed by oxiquill build; for a narrower regeneration, run clean followed by the required generation command.

For repeated release Rust rebuilds, the optimizer-result cache applies only when wasm-opt is on PATH and the unoptimized Wasm bytes repeat. It keys those bytes and size, optimizer version and executable hash, arguments, schema version, and BINARYEN_* variables. It does not speed up dev builds or fresh checkouts. Corrupt entries regenerate automatically; cache access errors allow optimization to continue without caching. Run oxiquill clean or pnpm build:clean to remove cacheDir/build-cache/wasm-opt while keeping verified downloads.

Compiler caches in cacheDir/build-cache normally survive cell edits and failed builds. Rust uses a persistent Cargo target (or your explicit CARGO_TARGET_DIR); Haskell keeps separate mode/compiler-version caches with stable source timestamps. Edited or truncated published files regenerate automatically. For suspected compiler-cache corruption or changes to ancestor/Cargo-home configuration or other out-of-tree build inputs, use a clean rebuild. If you set an external CARGO_TARGET_DIR, manage that user-owned cache separately; Oxiquill clean does not delete it.

oxiquill build --force clears only Astro’s content cache and does not force package or runtime rebuilding. Generated ownership data removes stale language output when the final cell of that language disappears. Never repair generated manifests, ownership markers, Wasm, Pyodide files, licenses, or dist by hand.

If the problem persists, open a GitHub issue with the Oxiquill/Node/tool versions, operating system, command, complete concise diagnostic, and a minimal reproducer. Use private vulnerability reporting for security-sensitive details.

Run pnpm exec oxiquill build --explain to see which language/module will rebuild and why, without waiting for the project lock or modifying output. Add --format json to consume the documented NDJSON schema in the CLI reference.

source-changed names affected pages and cells; helper-inputs-changed includes transitive helper inputs. mode-upgrade means release output is required after a dev build. output-missing and integrity-mismatch regenerate incomplete or corrupt outputs. previous-build-failed retries failed work while retaining the last complete registry. build-options-changed names changed variables without printing their values. dependencies-changed means a module’s resolved dependency versions, or the helper manifests taking part in the workspace build, changed. failure-unchanged keeps a failing development module’s last working build until its inputs change. generator-changed, package-changed, and toolchain-changed explain installation/tool changes; forced identifies an explicit runtime rebuild. cache-hit confirms verified reuse, and absent requires no language output.

A heartbeat means the named child process has produced no output for 30 seconds; it is not a completion-time estimate. Inspect the final phase summary for compiler versus optimizer time and cache reuse. A Rust failure names the module id and its pages for every grouping. Fix that page or helper and rerun. Production builds publish nothing when any module fails; the development runtime publishes every other module and keeps the failing module’s last working build, and one run reports every failing page.

For a wasm-bindgen version or checksum failure, use the expected version and exact cache path in the diagnostic. Install the matching official CLI on PATH, or remove the named corrupt tool-cache entry and retry the verified download. Release builds still run wasm-opt; if automatic setup fails, install Binaryen on PATH and retry. Do not disable verification or edit generated artifacts.

Rust compilation failures report the authored MDX path, line, column, and cell ID, followed by the compiler code/message and an underlined source excerpt. Definitions errors point to the definitions block. The generated Rust location remains available as secondary detail; helper and dependency errors retain their actual file locations. Generated wrappers are labeled as generated code.

Diagnostics come from the build itself: Cargo’s structured messages for each module are mapped to the authored cells without a second cargo check. Download, dependency-resolution, wasm-bindgen, and optimizer failures are reported as they occur. The original build error and exit status are retained. If a diagnostic cannot be mapped, the terminal says could not map this error to an authored cell. An unterminated string, character literal, or comment in a cell is reported by the compiler at that cell and fails only its module. Suggestions are translated only when all edit spans belong entirely to authored source.

During development, affected blocks show an inline compile-error panel through manifest HMR. The last successful Wasm remains available until the next successful compile, which clears the panel. A new failing block shows diagnostics without execution controls until it compiles. Production builds report errors only in the terminal. Locations refresh after edits and page renames.