Troubleshooting Guide

Common issues and solutions when working with Tairitsu browser-glue and Component Model.

Build Errors

wasm32-wasip2 target not found

Error:

text
1
2
3
error: can't find crate for `std`
  |
  = note: the `wasm32-wasip2` target may not be installed

Solution:

bash
1
rustup target add wasm32-wasip2

wit-bindgen version mismatch

Error:

text
1
error: failed to select a version for `wit-bindgen`

Solution: Ensure wit-bindgen version matches in Cargo.toml:

toml
1
2
[dependencies]
wit-bindgen = { version = "0.33", features = ["realloc"] }

dev-wasm profile not defined

Error:

text
1
error: profile `dev-wasm` is not defined

Solution: Add the profile to your workspace Cargo.toml:

toml
1
2
3
4
5
6
[profile.dev-wasm]
inherits = "release"
lto = true
opt-level = 'z'
codegen-units = 1
panic = "abort"

Projects created with tairitsu init already include this profile.

browser-glue runtime bundle not found

Error:

text
1
browser-glue runtime bundle (dist/runtime.js) not found

Solution:

  1. 1
    Run npm run build in packages/browser-glue/
  2. 2
    Or set the environment variable: TAIRITSU_RUNTIME_BUNDLE=/path/to/browser-glue/dist/runtime.js
  3. 3
    Or install via npm: npm install tairitsu-browser-glue

TypeScript compilation errors

Error:

text
1
error TS2307: Cannot find module './domGlue' or its corresponding type declarations.

Solution: Regenerate glue and rebuild:

bash
1
2
cd packages/browser-glue
npm run build

Runtime Errors

Missing host imports

Error:

text
1
Error: Component import "tairitsu-browser:full/document" was not satisfied

Solution:

  1. 1
    Ensure import map is configured:
html
1
2
3
4
5
6
7
<script type="importmap">
{
  "imports": {
    "tairitsu-browser:full/": "./browser-glue/"
  }
}
</script>
  1. 1
    Verify browser-glue files exist in output directory.

Component initialization failure

Error:

text
1
Error: Component instantiation failed: undefined import

Solution: Check that all required WIT imports have corresponding implementations in browser-glue.

jco transpile errors

Error:

text
1
Error: Failed to transpile component

Solution:

  1. 1
    Ensure jco is installed:
bash
1
npm install -g @bytecodealliance/jco
  1. 1
    Verify WASM component is valid:
bash
1
wasm-tools print component.wasm

Debug Techniques

Enable debug logs

In browser console:

javascript
1
localStorage.setItem('debug', 'tairitsu:*');

Inspect WIT bindings

View generated bindings:

bash
1
cat packages/web/src/wit_platform.rs | head -100

Browser DevTools

  1. 1
    Open DevTools (F12)
  2. 2
    Check Console for errors
  3. 3
    Network tab for failed module loads
  4. 4
    Sources tab for debugging

Component validation

bash
1
2
3
4
5
# Validate component structure
wasm-tools validate component.wasm

# Print component contents
wasm-tools print component.wasm

Common Issues

Handle not found

Symptom: null returned from DOM operations

Cause: Handle was garbage collected or not registered

Solution: Ensure elements remain referenced in JavaScript

Event not firing

Symptom: Event handlers not called

Cause: Listener ID mismatch or event type incorrect

Solution: Check addEventListener returns valid listener ID

Memory leaks

Symptom: Increasing memory usage over time

Cause: Handles not released after use

Solution: Call dropHandle() when done with objects

Performance Issues

Slow component load

Solutions:

  1. 1
    Use release build: cargo build --release
  2. 2
    Enable LTO in Cargo.toml:
toml
1
2
3
[profile.release]
lto = true
opt-level = 'z'

High event latency

Solutions:

  1. 1
    Avoid synchronous operations in handlers
  2. 2
    Use requestAnimationFrame for visual updates
  3. 3
    Debounce rapid events

Getting Help

  1. 1
    Check existing issues: https://github.com/anomalyco/opencode/issues
  2. 2
    Review documentation in docs/ directory
  3. 3
    Examine example code in examples/website/