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

> Troubleshoot moeru-ai/airi issues like crashes and UI bugs. Learn fixes for Turborepo cache, Windows compatibility, and fadeOnHover settings to optimize your experience.

- Repository: [Moeru AI/airi](https://github.com/moeru-ai/airi)
- Tags: troubleshooting-guide
- Published: 2026-03-08

---

**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`](https://github.com/moeru-ai/airi/blob/main/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`](https://github.com/moeru-ai/airi/blob/main/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:

```typescript
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:

```bash
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:

```bash
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`](https://github.com/moeru-ai/airi/blob/main/apps/stage-pocket/src/utils/storage.ts):

```typescript
// 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`](https://github.com/moeru-ai/airi/blob/main/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:

```bash
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`](https://github.com/moeru-ai/airi/blob/main/packages/stage-ui/src/stores/modules/resource.ts):

```typescript
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:

```typescript
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`](https://github.com/moeru-ai/airi/blob/main/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`](https://github.com/moeru-ai/airi/blob/main/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:

```bash
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:

```bash
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:

```bash
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`](https://github.com/moeru-ai/airi/blob/main/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`](https://github.com/moeru-ai/airi/blob/main/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`](https://github.com/moeru-ai/airi/blob/main/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`.