Skip to content

[Bug] TUI black screen on startup: bun:sqlite import incompatible with OpenCode embedded JS runtimeΒ #3475

Closed

Description

@fjy8080

Description

First off β€” huge thanks for building OmO. It's an incredible piece of work that transforms how we use OpenCode. πŸ™

I ran into a black screen issue on Windows and spent some time digging into the root cause. Sharing my findings below in case it helps others, and to see if there's a path toward a proper fix.

Environment

Component Version
OS Windows 11 (x64)
OpenCode 1.4.6 (Go binary via npm)
oh-my-opencode 3.17.4
Bun 1.3.12
Node.js v22.22.2

Symptoms

After installing OmO and registering the plugin in opencode.json, running opencode shows a completely black/blank TUI. The process hangs and becomes unresponsive. Removing the plugin from config restores normal startup.

Root Cause

The plugin bundle (dist/index.js) contains a Bun-specific import at line 147678:

// src/plugin/ultrawork-db-model-override.ts
import { Database } from "bun:sqlite";

OpenCode's Go binary has an embedded JS runtime for loading plugins. This runtime does not support the bun: protocol. When the plugin is loaded synchronously at startup, this unresolved import blocks the main thread, preventing the TUI from rendering.

How I confirmed this

Using OpenCode's debug logging:

# With plugin β€” hangs after config loading, never reaches TUI initialization
opencode --print-logs --log-level DEBUG

# Pure mode (no plugins) β€” loads all TUI plugins normally
opencode --pure --print-logs --log-level DEBUG

In pure mode, logs show loading internal tui plugin entries immediately. With the plugin, the process stops at config loading and never reaches TUI plugin initialization.

Additionally, the models.dev fetch during plugin init times out in China (GFW), which adds to the startup delay β€” but the primary blocker is the bun:sqlite import.

Workaround

I was able to fix the black screen by replacing the bun:sqlite import with a safe stub:

node -e "
const fs = require('fs');
const home = process.env.HOME || process.env.USERPROFILE;
const targets = [
  home + '/.cache/opencode/packages/oh-my-openagent@latest/node_modules/oh-my-openagent/dist/index.js',
  home + '/.config/opencode/node_modules/oh-my-opencode/dist/index.js'
].filter(p => { try { return fs.existsSync(p); } catch { return false; } });

const old = 'import { Database } from \"bun:sqlite\";';
const stub = 'var Database = class { constructor() { return { prepare: () => ({ get: () => null, run: () => null, all: () => [] }) }; } };';

targets.forEach(path => {
  let content = fs.readFileSync(path, 'utf-8');
  if (content.includes(old)) {
    content = content.replace(old, stub);
    fs.writeFileSync(path, content, 'utf-8');
    console.log('Patched: ' + path);
  }
});
"

After patching, OpenCode starts normally with full OmO functionality β€” Sisyphus agent, background agents, MCPs, ultrawork, etc. Only the ultrawork-db-model-override feature (model name override in session DB) is affected by the stub.

Limitation: The patch must be re-applied after every OmO update.

Suggested Fix

A few possible approaches, from simplest to most robust:

  1. Conditional import β€” Wrap the bun:sqlite import in a try/catch or use dynamic import() so the module degrades gracefully when Bun APIs are unavailable.

  2. Runtime detection β€” Check for typeof Bun !== 'undefined' before using Bun-specific APIs, and fall back to a no-op or alternative SQLite library.

  3. Build-time target β€” If the bundle is built with Bun, consider producing a runtime-agnostic variant for environments that don't ship the Bun runtime.

I'm happy to submit a PR if any of these approaches sound reasonable.

Additional Context for Users in China

Users in mainland China face an additional layer of difficulty:

  • bunx oh-my-opencode install may timeout due to npm registry access
  • opencode plugin command also times out when downloading packages
  • models.dev fetch during init is blocked by GFW

Workarounds: set npm config set registry https://registry.npmmirror.com/ before installation, and use OMO_SEND_ANONYMOUS_TELEMETRY=0 to skip analytics calls.

Related Issues

Happy to provide any additional debugging info if needed. Thanks again for the great project! πŸš€

Activity

  1. herjarsa commented on May 7, 2026

    @herjarsa
    Contributor

    Likely fixed by PR #3832 πŸŽ‰

    The TUI black screen is caused by the οΏ½un:sqlite import crashing Node.js's ESM loader at plugin load time. When the plugin fails to load, OpenCode doesn't show any agents and the TUI appears broken.

    PR #3832 fixes this by hiding the οΏ½un: import from the static parser, allowing the plugin to load gracefully in embedded JS runtimes.

    Please test once #3832 merges!

  2. Ganzhe2028 commented on May 7, 2026

    @Ganzhe2028

    Also hit this β€” same root cause, slightly different symptom.

    Environment

    • macOS, OpenCode 1.14.33 (Bun runtime)
    • oh-my-openagent was resolving @latest to cached 3.17.12

    Symptom
    Plugin loaded in config/doctor but only build and plan agents were available β€” all OMO agents (Sisyphus, Oracle, Librarian, etc.) disappeared. No black screen, just silently reduced to native agents only.

    Root cause
    Same bun:sqlite import in 3.17.12. OpenCode's embedded JS runtime rejected the bun: protocol at plugin load time, causing the plugin to fail silently. Since the plugin registered via the config hook never ran, the agent registry fell back to defaults.

    Fix

    1. Pinned [email protected] in opencode.json (this version already avoids the bun:sqlite crash for CLI/Bun runtime)
    2. Updated .zprofile to prefer /Users/mac/.opencode/bin/opencode (1.14.33) over Homebrew's older opencode 1.1.8, which also caused plugin diagnostic instability

    Verification

    oh-my-openagent doctor: System OK (opencode 1.14.33 Β· oh-my-openagent 3.17.15)
    opencode debug config: plugin agent "Sisyphus - Ultraworker" present
    opencode debug skill: both skill directories scanned correctly
    

    Pinning the version is more stable than floating @latest since the cached version can lag behind the fix. PR #3832 looks like the proper long-term fix β€” the new Function() wrapper avoids the static ESM parse issue entirely. Thanks for the detailed analysis on this issue!

  3. code-yeongyu commented on May 13, 2026

    @code-yeongyu
    Owner

    [sisyphus-bot] Closing this β€” fixed and shipped in v4.1.0 (also in v4.0.0+ for the specific bun:sqlite import).

    Thanks for the deep-dive analysis, @HP26666 β€” pinpointing line 147678 of dist/index.js, identifying that the embedded JS runtime can't resolve the bun: protocol, and even providing a working stub patch. That's a textbook bug report πŸ™

    What landed: PR #3832 (fix(desktop): hide bun:sqlite import from Node.js/Electron ESM loader) β€” the bun:sqlite import is now wrapped in new Function("return import('bun:sqlite')") so the specifier is hidden from the static ESM parser at parse/load time and only evaluated at runtime when globalThis.Bun is defined. Embedded JS runtimes (OpenCode Desktop Electron AND the Go-binary's embedded runtime) can now load the plugin without hitting the unresolvable bun: protocol.

    PR #3964 (in v4.1.0) further shims 19 other Bun.* call sites for full Electron/Node compatibility.

    @herjarsa already flagged that PR #3832 was the right fix here β€” confirmed.

    If you still see the TUI black screen on v4.1.0+ on OpenCode 1.4.6 or newer, please reopen with opencode --print-logs --log-level DEBUG output. Thanks πŸ™

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions