トラブルシューティング
最初の Oxiquill diagnostic から確認します。generation error は relevant tool/path を示し、authored cell では page、fence line、可能なら cell ID、正確な metadata field を含みます。
Runtime lock の競合と復旧
Section titled “Runtime lock の競合と復旧”runtime lock の待機表示は、別 command または dev 同期が project の generated artifact を使用中であることを示します。表示された command、PID、host、開始時刻、<cacheDir>/runtime.lock の path を確認し、holder の完了を待つか、その process を通常の方法で停止してください。CLI の既定の待機時間は1800秒です。build、check、docgen、clean、test-wasm の --lock-timeout <seconds> で変更し、0 なら即座に失敗します。watcher は期限なく待ち、取得後に最新の変更を同期します。
自動回収するのは、host が現在の host と一致し、PID が存在しない場合だけです。生存中の PID、権限不足による PID 確認失敗、古い開始時刻では回収しません。長時間の release Wasm build も lock を保持できます。
読めない・不正な record や別 host の record は owner 不明として扱います。この project を使用する Oxiquill process が動いていないことを確認してから、diagnostic に表示された正確な lock path を手動で削除し、再実行してください。共有 storage では別 host も確認します。build または同期の実行中に lock を削除しないでください。調整の単位は consumer project であり、出力 directory を共有する別 project 間は調整しません。
Build 中の source 変更
Section titled “Build 中の source 変更”Interactive cell sources changed after runtime generation started. は production build 中に cell または Rust helper input が変更されたことを示します。diagnostic は追加・削除・変更されたすべての cell と helper の path を表示し、cell では source や inputs などの変更 field も示します。
source の保存が完了してから oxiquill build を再実行してください。自動 retry は行いません。generation が失敗しても以前の完全な runtime は保持され、成功した build では cell manifest、MDX、Wasm が同じ generation に対応します。prose だけの変更では generation は変わらず、runtime artifact の cache を再利用します。
dev では未生成の cell に対し runtime watcher が再生成する旨を表示します。generation の完了を待ってください。production の整合性 checkpoint は dev server では実行しません。
Install と package resolution
Section titled “Install と package resolution”| 症状 | 対応 |
|---|---|
| Node version/syntax error | Node.js 24 以上を install し、pnpm/npm を起動する同じ shell で node --version を確認します。 |
oxiquill command not found | project dependency に追加し、package script または pnpm exec oxiquill から実行します。global install に依存しません。 |
| npm/pnpm が source や duplicate Preact を誤解決する | stale node_modules を除去して lockfile から reinstall し、documented package export だけを import します。deep import はしません。 |
| native Rollup/Vite addon を load できない | normal Node build を使います。ghc-wasm static Node が PATH の先頭なら normal Node を前に置くか OXIQUILL_NODE を設定します。 |
Rust と Wasm
Section titled “Rust と Wasm”| 症状 | 対応 |
|---|---|
| Rust toolchain/target がない | Rust/Cargo 1.85.0 以上を install し、rustup target add wasm32-unknown-unknown を実行します。 |
| Rust tool の download に失敗 | network を復旧するか、runtime pin と一致する wasm-bindgen と Binaryen 117 の wasm-opt を PATH に配置して再実行します。 |
| Unknown helper crate | crates: [...] を configured cratesDir 直下の package.name と一致させます。不要なら crates: [] を使います。 |
| Rust cell が stale、Wasm がない | pnpm wasm:dev で再生成し、.oxiquill/public/oxiquill を直接編集しません。 |
Rust/Cargo は 1.85.0 以上に対応します。wasm32-unknown-unknown target が必要です。Rust 1.85.0 を必須 CI で検証し、repository の開発には Rust 1.99.0 を使用します。Rust beta/nightly channel も数値 version が最低要件以上なら受け入れますが、未検証です。helper crate 自身がより新しい Rust を要求する場合は、その要件も満たす必要があります。
Oxiquill は、固定された runtime crate と完全に一致する wasm-bindgen CLI で各モジュールを bind します。PATH 上に一致する binary があればそれを使い、なければ host 向けの公式 prebuilt release を download して SHA-256 を検証します。一時的な download の失敗は再試行し、その後は同じ release asset を GitHub release API から取得します。この request は、GH_TOKEN または GITHUB_TOKEN が設定されていればそれを使うため、共有 CI runner の匿名 rate limit を避けられます。token は api.github.com にだけ送ります。wasm-bindgen と Binaryen wasm-opt の download はどちらもこの方針に従います。CLI を source から build することはないため、Rust 1.85 で足ります。公式 prebuilt release のない host では、一致する wasm-bindgen を PATH に配置してください。wasm-pack は使いません。
generated runtime の依存は exact pin を維持し、すべての Cargo build は --locked で実行します。生成 workspace の依存関係が変わるたびに、Oxiquill は runtime pin と、各 helper workspace 自身の Cargo.lock にある通常依存と build 依存の version から rust-cells/Cargo.lock の初期値を作り(dev-dependencies は無視します)、Cargo に一度だけ解決させます。どの helper lock にも記録されていない registry 依存は、その時点で利用できる互換性のある最新 version に解決されます。再現性が必要なら helper workspace の Cargo.lock を commit するか、exact pin にしてください。helper が Oxiquill の exact runtime pin と矛盾する version を要求すると、Cargo の error で解決に失敗します。serde = "=1.0.228" ではなく serde = "1" のように helper の制約を広げて pin された version を受け入れられるようにし、pnpm wasm:dev を再実行してください。生成 Cargo.lock は直接編集しません。
Haskell
Section titled “Haskell”| 症状 | 対応 |
|---|---|
wasm32-wasi-ghc がない | Linux/macOS に ghc-wasm 9.14 を install するか OXIQUILL_HASKELL_GHC へ compiler path を指定します。native Windows generation は非対応です。 |
| ghc-wasm を source 後に Astro/Vite が失敗する | normal Node.js 24 runtime を ghc-wasm static Node より前に置くか OXIQUILL_NODE を設定します。 |
| runtime unavailable/stale | compiler/cell error を直して pnpm wasm:dev を再実行し、generated status を編集せず diagnostic を確認します。 |
Python download と offline build
Section titled “Python download と offline build”| 症状 | 対応 |
|---|---|
| CDN/mirror request failure | DNS/TLS/proxy と mirror base を確認します。error は effective URL と HTTP/connection cause を示します。 |
| timeout/retry exhaustion | connectivity 回復後に retry するか complete verified cache を使います。各 attempt は30秒、合計3回までです。 |
| SHA-256 mismatch | 検証を bypass せず、named corrupt cache entry を削除して trusted source/mirror から取得します。 |
| offline cache miss | 同じ Oxiquill/Pyodide version で exact filename/hash を connected machine 上に用意し、verified cache を転送します。 |
| unsupported Python package | install 済み Pyodide lockfile にある package を使うか packages から除きます。 |
Config と path
Section titled “Config と path”command ごとに別 directory を使うように見える場合、同じ --config <path> を渡し、diagnostic が示す conflicting field を確認します。relative child path は documented parent から解決されます。Astro と paths に正規化後の location が異なる値を組み合わせないでください。
clean は unsafe field、absolute resolved path、conflicting path role を報告します。cleanup root が authored input、public root、project/repository metadata、dependency、framework、persistent download cache、別の generated role と重なる場合は、生成専用 directory へ移してください。symlink alias でも検証を迂回できません。
custom root で .oxiquill-ownership.json の欠落・不一致が報告された場合、marker を手動作成しないでください。authored file を保持または移動し、存在しないか空の生成専用 directory を選んで、対応する generation/build command を再実行すると Oxiquill が ownership を確立します。ownership marker 導入前に作られた古い custom output は、内容を確認して明示的に空にしてから claim してください。
clean は削除前に3つの target をすべて preflight します。そのため、一つの target の diagnostic が出ても、他の generated root、authored file、repository/dependency state、.cache/oxiquill/downloads/v1 は変更されません。報告された config/ownership を修正してから pnpm clean を再実行します。
Worker timeout と browser failure
Section titled “Worker timeout と browser failure”cell timeout の default は 30,000 ms です。timeoutMs には 1 以上 2,147,483,647 以下の integer millisecond を指定できます。timeout 時は failed language worker を終了し、その worker が持つ request を reject して、次回用に fresh worker を作ります。workload を減らすか妥当な長い timeout を選び、security sandbox として使わないでください。
browser failure では site rebuild、public/oxiquill 下の expected file、deployment が .wasm/JavaScript asset を保持すること、configured base path と deploy URL の一致を確認します。supported current Chromium、Firefox、WebKit で test してください。
Stale output
Section titled “Stale output”Oxiquill repository の pnpm build は変更のない package output と runtime artifact を再利用し、Astro は static site output を作り直します。source と generated output が一致しない場合は pnpm build:clean を実行すると、verified download cache を保持しながら package、runtime、site を最初から再生成できます。consumer project では oxiquill clean 後に oxiquill build を実行します。特定の生成物だけが必要なら clean 後に対応する generation command を実行してください。
Release Rust の再 build で optimizer-result cache が有効になるのは、wasm-opt が PATH にあり、最適化前の Wasm bytes が以前と同じ場合です。key はその bytes と size、optimizer の version と executable hash、引数、schema version、BINARYEN_* 環境変数です。dev build や新しい checkout の高速化にはなりません。破損した entry は自動再生成し、cache access error があっても cache を使わず最適化を続行します。oxiquill clean または pnpm build:clean で cacheDir/build-cache/wasm-opt を削除でき、verified download は保持します。
cacheDir/build-cache の compiler cache は通常、cell 編集や build failure 後も保持します。Rust は永続 Cargo target(または明示した CARGO_TARGET_DIR)を使用し、Haskell は mode/compiler version ごとの cache と安定した source timestamp を使用します。編集・切り詰められた published file は自動再生成します。compiler cache の破損が疑われる場合や、ancestor/Cargo-home config など workspace 外の build input を変更した場合は clean rebuild を実行してください。外部の CARGO_TARGET_DIR を指定した場合、その user-owned cache は別途管理してください。Oxiquill clean では削除しません。
oxiquill build --force が消去するのは Astro の content cache だけで、package や runtime の再ビルドを強制しません。generated ownership data は最後の cell が消えた language の stale output を除去します。manifest、ownership marker、Wasm、Pyodide file、license、dist を手動修正しないでください。
解決しない場合は GitHub issue に Oxiquill/Node/tool version、OS、command、完全で簡潔な diagnostic、minimal reproducer を添えてください。security-sensitive detail は private vulnerability reporting を使います。
遅いビルド・繰り返す再ビルドの確認
Section titled “遅いビルド・繰り返す再ビルドの確認”pnpm exec oxiquill build --explain で、lock を待たず出力を変更せずに、再ビルドする言語・モジュールと理由を確認できます。--format json の NDJSON スキーマは CLI リファレンス を参照してください。
source-changed はページとセル、helper-inputs-changed は推移的な helper 入力の変更を示します。mode-upgrade は開発成果物からリリースへの更新です。output-missing と integrity-mismatch は不足・破損出力を再生成します。previous-build-failed は以前の完全な registry を維持して失敗した処理を再試行します。build-options-changed は値を表示せず変数名だけを示します。dependencies-changed はモジュールの解決済み依存 version、または workspace の build に参加する helper manifest の変更です。failure-unchanged は、入力が変わるまで失敗した開発用モジュールの最後に動作した build を維持します。generator-changed、package-changed、toolchain-changed は実装・パッケージ・ツール変更、forced は明示的再ビルドです。cache-hit は検証済み再利用、absent は対象言語の出力が不要であることを示します。
Heartbeat は対象プロセスに 30 秒間出力がないという意味で、完了予測ではありません。最後のフェーズ集計でコンパイル、最適化、キャッシュ再利用を確認してください。どのグループ化でも、Rust の失敗にはモジュール ID とページが含まれます。対象のページや helper を修正して再実行してください。本番ビルドはいずれかのモジュールが失敗すると何も公開しません。開発ランタイムは他のモジュールをすべて公開し、失敗したモジュールは最後に動作したビルドを維持します。1 回の実行で失敗したページをすべて報告します。
wasm-bindgen のバージョン・checksum エラーでは、診断の期待バージョンとキャッシュパスを確認します。一致する公式 CLI を PATH にインストールするか、示された破損キャッシュだけを削除して再取得してください。リリースでは wasm-opt を引き続き実行します。自動セットアップが失敗する場合は Binaryen を PATH にインストールしてください。検証の無効化や生成物の直接編集は不要です。
Rust コンパイラーの位置情報
Section titled “Rust コンパイラーの位置情報”Rust のコンパイルエラーには、作成元 MDX のパス、行、列、セル ID、診断コードとメッセージ、下線付きのソース抜粋が表示されます。定義内のエラーはその定義ブロックを指します。生成された Rust の位置も補足情報として残り、ヘルパークレートや依存クレートのエラーは実際のファイル位置を保持します。ラッパー内のエラーは生成コードとして明示します。
診断はビルド自体から取得します。各モジュールについて Cargo が出力する構造化メッセージを作成元のセルに対応付けるため、cargo check を追加で実行しません。ダウンロード、依存関係解決、wasm-bindgen、最適化の失敗は発生した時点で報告します。元のエラーと終了ステータスを保持し、診断を対応付けられない場合は could not map this error to an authored cell と表示します。セル内で閉じていない文字列、文字リテラル、コメントは、コンパイラがそのセルの位置で報告し、そのモジュールだけが失敗します。修正候補は編集範囲全体が作成元ソースに収まる場合のみ位置を変換します。
開発中は manifest HMR を通じ、該当ブロックにコンパイルエラーパネルを表示します。最後に成功した Wasm は引き続き利用でき、次のコンパイル成功時にパネルが消えます。初回から失敗する新規ブロックでは、成功するまで診断のみを表示します。本番ビルドはターミナルにのみエラーを表示します。編集やページ名の変更後も位置情報を更新します。