> ## Documentation Index
> Fetch the complete documentation index at: https://docs.origami.techmitten.com/llms.txt
> Use this file to discover all available pages before exploring further.

# WebGPU Troubleshooting and Browser Fixes for Origami AI

> Diagnose and fix WebGPU browser issues in Origami AI, from not-detected errors to device-lost crashes, with a cloud AI fallback option.

WebGPU is the browser technology that powers local AI model inference in Origami AI. When WebGPU is working correctly, your GPU runs AI models directly in your browser — no data leaves your device. This page helps you identify what is wrong when WebGPU is not working and walks you through your options, including how to use cloud AI if your device does not support WebGPU.

<Note>
  For full hardware and browser requirements, see the [Requirements](/requirements) page.
</Note>

***

## WebGPU Not Detected

### Symptoms

* Origami AI shows a **"WebGPU not supported"** message
* You cannot load or use local AI models
* The AI Assistant Chat page is unavailable

### Solutions

<Steps>
  <Step title="Enable hardware acceleration in your browser">
    WebGPU requires hardware acceleration. If it is turned off, WebGPU will not be available even on a capable GPU.

    * **Chrome:** Go to `chrome://settings/system` and turn on **Use hardware acceleration when available**, then relaunch the browser.
    * **Edge:** Go to `edge://settings/system` and enable the same setting.
  </Step>

  <Step title="Update your GPU drivers">
    Outdated drivers are a common cause of WebGPU failures. Visit your GPU manufacturer's website (NVIDIA, AMD, Intel, or Apple) and install the latest available drivers for your hardware. Restart your computer after updating.
  </Step>

  <Step title="Verify WebGPU status in your browser">
    Check your browser's internal GPU diagnostics page to confirm WebGPU is active:

    * **Chrome:** Navigate to `chrome://gpu` and look for the line **WebGPU: Hardware accelerated**. If it says "Disabled" or "Software only," hardware acceleration is off or your driver does not support it.
    * **Edge:** Navigate to `edge://gpu` and look for the same WebGPU line.
    * **Firefox Nightly:** Navigate to `about:config`, search for `dom.webgpu.enabled`, and set it to `true`. Restart Firefox after saving the change.
  </Step>

  <Step title="Confirm your browser version supports WebGPU">
    WebGPU requires a recent browser version. See the [Browser Compatibility](#browser-compatibility) table below for the minimum versions. If your browser is older, update it or try Chrome or Edge 113+.
  </Step>

  <Step title="Restart your browser and refresh the page">
    After making any changes, fully close and reopen your browser, then navigate back to Origami AI.
  </Step>

  <Step title="Try a different browser">
    If the issue persists in one browser, try Chrome or Edge — both have the most mature WebGPU implementations. If WebGPU works in a different browser, the problem is specific to your original browser's configuration.
  </Step>
</Steps>

***

## WebGPU Fallback: Use Cloud AI

If your browser or device does not support WebGPU, you can still use the vast majority of Origami AI's features by connecting a cloud AI provider.

**What still works without WebGPU:**

* All AI features (narration script drafting, OCR, slide generation, Shorts scripts, and AI Assistant chat) when routed through a connected cloud provider
* Screen recording and auto-zoom
* Manual video editing, audio mixing, and timeline adjustments
* Video rendering with FFmpeg.wasm (this does not require WebGPU)

**What requires WebGPU:**

* Running local WebLLM models directly on your device

**How to connect a cloud AI provider:**

1. Open **⚙️ Settings → API**.
2. Enter your preferred OpenAI-compatible endpoint base URL, model name, and API key.
3. Supported providers include Gemini, OpenRouter, Groq, Ollama, and any OpenAI-compatible service.
4. Your credentials are saved locally in your browser and never sent to Origami AI's servers.

<Note>
  For the AI Assistant Chat, enable **Use for Assistant** in **Settings → API** to route chat messages through your cloud provider instead of a local model.
</Note>

***

## "Device Lost" Error

### Symptoms

* You see a **"Device lost"** error during inference or chat
* The GPU becomes unresponsive mid-generation
* The browser tab freezes or crashes after the error appears

### Solutions

1. **Refresh the page immediately.** A device-lost event leaves the GPU in a bad state. Reload Origami AI to reset the WebGPU context before trying again.
2. **Close other browser tabs.** Other tabs with GPU-heavy content (3D apps, video players, WebGL sites) consume VRAM that Origami AI needs. Close them to free GPU memory.
3. **Switch to a smaller model.** Large models demand more VRAM. Try **Gemma 2 2B** or **Llama 3.2 1B** — both perform well and are much lighter on GPU memory.
4. **Update your GPU drivers.** Device-lost errors are sometimes caused by driver bugs that are fixed in newer releases. See your GPU manufacturer's website for the latest driver.
5. **Switch to a remote API.** If device-lost errors happen repeatedly, offload inference to a cloud provider via **Settings → API** to remove GPU pressure entirely.

***

## Browser Compatibility

| Browser               | Minimum Version      | WebGPU Support                                             |
| --------------------- | -------------------- | ---------------------------------------------------------- |
| **Chrome / Chromium** | 113+                 | Full support                                               |
| **Edge**              | 113+                 | Full support                                               |
| **Firefox Nightly**   | Latest Nightly build | Supported with `dom.webgpu.enabled` flag in `about:config` |
| **Safari**            | 18+ (macOS Sonoma+)  | Supported for desktop workflows                            |

<Warning>
  Firefox's standard release channel does not yet support WebGPU. You must use **Firefox Nightly** and manually enable the flag. For the most reliable experience, use Chrome or Edge 113+.
</Warning>

***

## FFmpeg.wasm / SharedArrayBuffer Errors

### Symptoms

* You see **"SharedArrayBuffer is not defined"** in the browser console
* FFmpeg.wasm fails to initialize
* Video rendering never starts, even though other features work

### Cause

These errors appear when Origami AI is loaded directly from the filesystem (`file://` protocol) rather than being served by a web server. FFmpeg.wasm requires specific security headers (`Cross-Origin-Opener-Policy` and `Cross-Origin-Embedder-Policy`) that are only present when the app is served correctly.

### Solutions

1. **Always access Origami AI through a server.** Use the hosted app at [https://origami.techmitten.com/](https://origami.techmitten.com/) or start the local dev server:
   ```bash theme={null}
   npm run dev
   ```
   Then open **[http://localhost:3006](http://localhost:3006)** — never open `index.html` directly.

2. **Do not open static build files with `file://`.** Even after running `npm run build`, use `npm run preview` to serve the build locally and access it at **[http://localhost:4173](http://localhost:4173)**.

3. **Verify COOP/COEP headers are present.** Open DevTools (`F12`) → **Network** tab → click any request → check the response headers for:

   * `Cross-Origin-Opener-Policy: same-origin`
   * `Cross-Origin-Embedder-Policy: credentialless`

   If these headers are missing, restart the dev server and hard-refresh (`Ctrl+Shift+R` / `Cmd+Shift+R`).