moeru-ai/airi Troubleshooting Guide: Common Issues and Platform-Specific Fixes

Most AIRI crashes and UI bugs can be resolved by clearing the Turborepo cache, switching to the nightly desktop build for Windows compatibility, or disabling the fadeOnHover feature via Shift+Alt+I or packages/stage-ui/src/stores/settings/general.ts.

The AIRI repository is a heterogeneous monorepo maintained by moeru-ai that combines Electron-based desktop applications, Vite-powered web interfaces, Capacitor mobile builds, Rust native modules, and micro-service backends. Due to this complex architecture spanning multiple platforms and build tools, users frequently encounter specific moeru-ai/airi troubleshooting scenarios related to native compilation, certificate handling, and build pipeline migrations.

Desktop (Tamagotchi) Mouse Blocking and Windows Crashes

Fade on Hover Captures Mouse Events

The fade on hover feature intentionally adds a transparent overlay to create a visual fade effect, but this overlay captures all mouse events and prevents interaction with underlying applications. This behavior is controlled in packages/stage-ui/src/stores/settings/general.ts via the fadeOnHover boolean flag.

Press Shift + Alt + I to toggle this feature off temporarily. For a permanent fix, modify the settings store directly:

import { settingsStore } from '@proj-airi/stage-ui/src/stores/settings/general'

// Disable mouse-blocking fade behavior
settingsStore.update({ fadeOnHover: false })

Windows Native Module Crashes

Version 0.7 introduced a complete rewrite of the ASR/STT pipeline and migrated from unbuild to tsdown and from Vite to rolldown-vite. The Windows toolchain is particularly fragile because it must compile native Rust crates (including candle and ONNX Runtime) and link against CUDA when available.

If AIRI crashes on launch or shows "module not found" errors on Windows:

1. Run the nightly build using pnpm dev:tamagotchi which contains the latest Windows fixes.

2. Install the Microsoft C++ Build Tools and update the Rust toolchain: rustup update.

3. Clean the monorepo cache to remove stale native artifacts:

pnpm exec turborepo prune
pnpm install

iOS and Mobile Development Issues

WKWebView Certificate Trust Errors

The AIRI dev server generates temporary self-signed certificates for HTTPS. iOS WKWebView cannot validate these certificates because iOS does not import host OS certificates automatically, resulting in "not trusted" errors when testing on physical devices.

Use HTTP for local iOS testing:

pnpm dev -- --https false

For production builds, provide a CA-signed certificate. If you must use HTTPS with a self-signed cert, manually install the certificate on the iOS device via Settings → General → VPN & Device Management, then enable full trust under Settings → General → About → Certificate Trust Settings.

Onboarding Modal Resets in Safari

The onboarding flag hasSeenOnboarding persists in localStorage under the key airi:onboarding. Safari's incognito mode and Intelligent Tracking Prevention clear localStorage each session, causing the onboarding screen to reappear repeatedly.

Fix this by switching to IndexedDB persistence in apps/stage-pocket/src/utils/storage.ts:

// apps/stage-pocket/src/utils/storage.ts
export const storageConfig = {
  useIndexedDB: true,  // Persist across Safari sessions
  key: 'airi:onboarding'
}

Alternatively, disable the onboarding modal entirely in packages/stage-ui/src/stores/settings/general.ts.

Build Pipeline and Toolchain Errors

Stub and Unbuild Migration Failures

After the migration from unbuild to tsdown, leftover stub scripts in scripts/postinstall may still reference old output paths like ./dist/index.mjs, causing export resolution errors during pnpm build.

Resolve this by:

1. Deleting node_modules/.cache and reinstalling: pnpm install.

2. Ensuring all @proj-airi/* packages are updated to versions using the new build system.

3. Adding "type": "module" to any package still using legacy unbuild configurations.

Nix Flake Attribute Resolution

Running nix run github:moeru-ai/airi on Nix versions older than 2.9 produces an "unknown attribute 'airi'" error because the flake expects explicit attribute selection.

Upgrade Nix and use the exact attribute path:

nix-env -iA nixpkgs.nix  # Upgrade to latest

nix run github:moeru-ai/airi#airi  # Explicit attribute

nix flake check  # Verify flake integrity

Web UI and Resource Management

Resource Island Widget Stuck on Screen

The floating download progress widget listens for downloadFinished events from the internal resource manager. Custom models that bypass the standard registration may fail to emit this event, leaving the widget visible indefinitely.

Ensure all custom models register via registerResource() in packages/stage-ui/src/stores/modules/resource.ts:

import { resourceStore } from '@proj-airi/stage-ui/src/stores/modules/resource'

resourceStore.register({
  id: 'custom-asr',
  name: 'My Custom ASR',
  url: 'https://my.cdn/models/custom-asr.onnx',
  type: 'asr',
})

If the widget remains stuck after a completed download, manually clear the state from the browser console:

resourceStore.clear()

Minecraft Mod Hot-Reload Limitations

The Minecraft agent runs inside a Mineflayer bot that only refreshes world state on full client reload. There is no hot-module-replacement for Lua data.lua scripts, forcing complete restarts for every change.

For efficient debugging:

1. Extract custom logic into separate Node.js modules called by the bot rather than embedding in Lua.

2. Use the debug/tool-executor.ts helper to trigger bot reloads via the /reload command.

3. Run the bot in Docker with volume mounts, then docker exec a reload command to avoid full client restarts.

General Diagnostic Workflow

When encountering undefined errors, follow this systematic approach.

Enable debug logging across all components by setting the environment variable:

DEBUG=airi:* pnpm dev

Logs are handled by @proj-airi/logger defined in services/*/src/utils/logger.ts.

Run the appropriate development script for your target platform:

pnpm dev              # Web version

pnpm dev:tamagotchi   # Desktop (Electron)

pnpm dev:pocket       # Mobile (Capacitor)

Clear the Turborepo cache to eliminate stale type-checking artifacts and native build residues:

pnpm exec turborepo prune
pnpm install

Summary

• Desktop mouse blocking is caused by the fadeOnHover feature in packages/stage-ui/src/stores/settings/general.ts and can be toggled with Shift+Alt+I.

• Windows crashes after v0.7 require the nightly build, updated Rust toolchain, and pnpm exec turborepo prune to clear native module cache.

• iOS certificate errors occur because WKWebView cannot trust host OS self-signed certs; use HTTP for local testing or manually install the certificate on the device.

• Build failures from unbuild migration are fixed by deleting node_modules/.cache and ensuring "type": "module" is set in package.json files.

• Resource Island sticks when custom models bypass registerResource() in packages/stage-ui/src/stores/modules/resource.ts.

• Nix flakes require version 2.9+ and explicit attribute syntax: nix run github:moeru-ai/airi#airi.

Frequently Asked Questions

Why does the AIRI desktop app block mouse clicks on other windows?

The fade on hover feature intentionally captures mouse events to create a visual fade effect on the AI character window. This is controlled by the fadeOnHover flag in packages/stage-ui/src/stores/settings/general.ts. Press Shift+Alt+I to toggle it off temporarily, or update the store programmatically to disable it permanently.

How do I fix Windows build failures after the v0.7 update?

Version 0.7 migrated the build system from unbuild to tsdown and introduced new Rust native dependencies. Install the Microsoft C++ Build Tools, run rustup update to get the latest Rust toolchain, and execute pnpm exec turborepo prune && pnpm install to clear stale native artifacts. Use pnpm dev:tamagotchi to run the nightly build which contains Windows-specific fixes.

Why won't my iOS device trust the AIRI development certificate?

iOS WKWebView maintains its own certificate trust store separate from macOS. The dev server's self-signed certificate is not automatically trusted on iOS devices. For local development, start the server with --https false to use HTTP. For production, provide a CA-signed certificate, or manually install the dev certificate via Settings → General → VPN & Device Management on the iOS device.

How do I clear stale build artifacts in the AIRI monorepo?

Run pnpm exec turborepo prune to clean the Turborepo cache, then delete node_modules/.cache and run pnpm install to regenerate dependencies. This resolves "module not found" errors and type-checking failures caused by the migration from unbuild to tsdown, particularly in packages/stage-ui and packages/vite-plugin-warpdrive.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}