OpenCode Compatibility & Troubleshooting Guide

Last Updated: April 17, 2026
Status: Active
Scope: OpenCode version compatibility, plugin interface changes, NAPI native addon issues

📋 Version Compatibility Matrix

OpenCode Version	Status	LanceDB Native	SDK Type Changes	Notes
v1.2.0 - v1.3.7	✅ Stable	✅ Working	None	Fully supported
v1.3.8 - v1.3.13	⚠️ Conditional	⚠️ Cache-dependent	N/A	Works on fresh install; may fail on skip-version upgrade (see below)
v1.3.14 - v1.3.17	✅ Verified	✅ Working	Minor	SDK v1.3.14 compatible; Config.plugin type updated
v1.4.0 - v1.4.3	✅ Verified	✅ Working	Breaking (SDK only)	Fully functional; see SDK breaking changes below
v1.4.4 - v1.4.7	✅ Working	✅ Working	Type update	Update test mock; `ask()` now returns `Effect`

⚠️ OpenCode v1.4.4+ Compatibility (SDK Type Change)

Status: ⚠️ Type Signature Update Required

OpenCode v1.4.4 - v1.4.7 contain SDK type changes that affect test compilation:

Type Change: `ToolContext.ask()` Return Type

Version	Change	Impact
v1.4.4	SDK error handling improvement	None
v1.4.5	OTLP telemetry export	None
v1.4.6	Bug fixes	None
v1.4.7	Type change	`ask()` returns `Effect<void>` instead of `Promise<void>`

Error Details

When running npm run test:effectiveness with SDK 1.4.7:

test/regression/plugin.test.ts(273,98): error TS2345: Argument of type 
'{ sessionID: string; messageID: string; agent: string; directory: string; 
worktree: string; abort: AbortSignal; metadata(): void; ask(): Promise<void>; }' 
is not assignable to parameter of type 'ToolContext'.

The types returned by 'ask(...)' are incompatible between these types.
  Type 'Promise<void>' is missing the following properties from type 
  'Effect<void, never, never>': [TypeId], pipe, asEffect, [Symbol.iterator]

Root Cause

The @opencode-ai/plugin package updated ToolContext.ask() return type to Effect<void> instead of Promise<void>. This is part of OpenCode's ongoing migration to Effect-based architecture (see PRs #8269, #8328).

Note: This is a type signature change only — not a runtime incompatibility. The actual functionality works fine; only the TypeScript compiler complains.

Fix: Update Test Mock

The test mock in test/regression/plugin.test.ts (line 197) needs to be updated:

// Before (SDK 1.4.3)
const context = {
  // ... other fields
  async ask() {},  // Returns Promise<void> - TypeScript infers this
};

// After (SDK 1.4.7)
import { Effect } from "effect";

const context = {
  // ... other fields
  ask: () => Effect.void,  // Returns Effect<void> - matches SDK type
};

Quick Fix Command

# Apply the fix to test/regression/plugin.test.ts
# 1. Add import at top of file:
sed -i '1s/^/import { Effect } from "effect";\n/' test/regression/plugin.test.ts

# 2. Update the context mock:
sed -i 's/async ask() {},/ask: () => Effect.void,/' test/regression/plugin.test.ts

Note: Effect.void is the correct method in effect v4.0.0-beta.48 (not Effect.unit).

✅ OpenCode v1.4.3 Compatibility (Verified April 10, 2026)

Status: ✅ Fully Compatible

lancedb-opencode-pro v0.8.1 has been verified working with OpenCode v1.4.3:

✅ LanceDB NAPI native addon loads correctly
✅ TypeScript compilation passes with SDK v1.4.3 types
✅ Build succeeds (npm run build)
✅ All unit and regression tests pass (199 pass, 0 fail)
✅ E2E tests pass (auto-capture, search, feedback, episodic learning)
✅ npm run verify:full clean in Docker (OpenCode v1.4.3 environment)

Recommendation: Upgrade to v1.4.3. It is the current stable release.

🔍 Issue #20623 — Root Cause Clarification

Original Report

Issue #20623: "Plugins with native NAPI dependencies return empty module ({}) since v1.3.8 plugin loader refactor"

Status: Open (but root cause clarified — see below)

Author's Update: The Real Root Cause

The issue author subsequently discovered the root cause was stale plugin cache from skip-version upgrades, not a fundamental plugin loader bug:

After further testing, the issue does not reproduce when upgrading through each version sequentially (1.3.7 → 1.3.8 → ... → 1.3.13). Every version works correctly when upgraded this way.

The issue only occurred after the desktop app auto-updated directly from an older version to 1.3.13. The plugin cache (~/.cache/opencode/node_modules/) was stale or corrupted from the jump.

What actually happened:

Skip-version upgrade (e.g. 1.3.7 → 1.3.13):
  Plugin cache ~/.cache/opencode/node_modules/ NOT rebuilt
  → NAPI .node binaries exist on disk
  → New plugin loader cannot resolve them from stale cache
  → import("@lancedb/lancedb") returns {}
  → All memory tools fail

Fresh install or sequential upgrade:
  bun install rebuilds cache at each version step
  → NAPI .node binaries correctly linked
  → import("@lancedb/lancedb") works normally ✅

Why v1.4.3 Works

Fresh install or upgrade through recent versions rebuilds cache correctly
The Dockerfile in this project pins OpenCode version explicitly, ensuring clean install
No fundamental NAPI loading change was needed — the loader is correct for fresh environments

🔴 If You See "Memory store unavailable"

Step 1: Clear the plugin cache (fixes most cases)

rm -rf ~/.cache/opencode/node_modules/
# Restart OpenCode — it will reinstall all plugins fresh

Step 2: Verify Ollama is accessible

curl http://127.0.0.1:11434/api/tags
curl http://127.0.0.1:11434/api/embeddings \
  -d '{"model":"nomic-embed-text","prompt":"test"}'

Step 3: Check plugin installation

ls ~/.cache/opencode/node_modules/lancedb-opencode-pro/dist/
# Should list: index.js, store.js, etc.

Step 4: Advanced — test native module loading directly

cd ~/.cache/opencode
node -e "const l = require('./node_modules/@lancedb/lancedb'); console.log(Object.keys(l))"
# Should print: [ 'connect', ... ] — not empty []

🔧 Solutions

Solution 1: Clear Plugin Cache (RECOMMENDED)

Status: ✅ Resolves most NAPI loading issues

rm -rf ~/.cache/opencode/node_modules/
# Restart OpenCode

Solution 2: Upgrade to OpenCode v1.4.3

Status: ✅ Verified working (April 10, 2026)

opencode upgrade
opencode --version  # Should output: 1.4.3

If upgrading from a very old version, clear cache after upgrade:

rm -rf ~/.cache/opencode/node_modules/

Solution 3: Downgrade to v1.3.7 (Legacy Workaround — Not Recommended)

Only use if you specifically need v1.3.x:

opencode upgrade 1.3.7

📋 Version Compatibility Details

v1.3.14 SDK Changes

Config.plugin type: Changed from string[] to (string | [string, PluginOptions])[]
Fix applied in v0.7.0: Updated src/config.ts to import Config from @opencode-ai/plugin

v1.4.0+ Breaking SDK Changes

Change	Before (v1.3.x)	After (v1.4.0+)
Diff metadata	`{to, from, patch}`	`{patch}` only
UserMessage.variant	Top-level field	`msg.model.variant`

Impact on lancedb-opencode-pro: Minimal. The plugin does not consume diff metadata or UserMessage.variant. All hooks continue to work unchanged.

v1.4.7 Type Change: ToolContext.ask()

Change	Before (v1.4.3)	After (v1.4.7+)
ToolContext.ask()	`Promise<void>`	`Effect<void, never, never>`

Impact on lancedb-opencode-pro: Type signature update only. Update test mock to use Effect.unit instead of async function. No runtime changes needed.

Source: This change is part of OpenCode's Effect-based architecture migration (see anomalyco/opencode#8269, anomalyco/opencode#8328).

📊 OpenCode SDK Version History (1.4.3 - 1.4.7)

Version	Date	SDK Changes	Impact
v1.4.7	Apr 16, 2026	`ToolContext.ask()` type → `Effect<void>`	🟡 Type update only
v1.4.6	Apr 15, 2026	None	✅ None
v1.4.5	Apr 15, 2026	OTLP telemetry export	✅ None
v1.4.4	Apr 15, 2026	SDK HTML error message improvement	✅ None
v1.4.3	Apr 10, 2026	None	✅ Baseline

Full Changelog

v1.4.7:

Core: GitHub Copilot gpt-5-mini low reasoning, workspaces auth context, Azure store=true default
TUI: Paste fix, --agent command line
Desktop: Beta/Dev badge

v1.4.6:

Core: Snapshot staging fix, OTEL header parsing fix

v1.4.5:

Core: OTLP telemetry export, question API schema exposed

v1.4.4:

SDK: Clear error when older server responds with HTML
Core: Logger context during prompt runs, MCP OAuth persistence
Extensions: Custom workspace adaptors

v1.4.3:

Core: Fixed agent create for OpenAI OAuth accounts

📚 Hook Stability Reference

Hook	Stability	Used by Plugin
`config`	✅ Stable	✅ Yes
`event`	✅ Stable	✅ Yes
`tool`	✅ Stable	✅ Yes
`experimental.text.complete`	⚠️ Undocumented	✅ Yes
`experimental.chat.system.transform`	⚠️ Community-only	✅ Yes
`session.created`, `session.idle`, `session.end`	✅ Stable	✅ Yes (via event hook)

🔍 Related Issues

Issue	Component	Status	Impact
#20623	Plugin cache on skip-version upgrade	Open (root cause: stale cache)	🟡 Only affects skip-version upgraders; clear cache to fix
#20112	Plugin loader refactor	Merged	Was initially blamed; not the actual cause
#20140	Fix entrypoint path	Merged v1.3.9	Fixed separate entrypoint bug

📊 Troubleshooting Decision Tree

Memory tools failing?
│
├─ "Memory store unavailable"?
│  ├─ Clear cache: rm -rf ~/.cache/opencode/node_modules/
│  │  └─ Restart OpenCode → Fixed? ✅ Done
│  │
│  └─ Still failing? Check Ollama: curl http://127.0.0.1:11434/api/tags
│     ├─ NO → Fix Ollama access first
│     └─ YES → Check logs: ~/.local/share/opencode/log/
│
└─ Plugin not loading?
   └─ Check opencode.json config has "lancedb-opencode-pro" in plugin list

📚 Related Documentation

QUICK_START.md — Prerequisites & setup
DEVELOPMENT_WORKFLOW.md — For developers
ADVANCED_CONFIG.md — Configuration reference

🎯 Summary

Aspect	Status	Action
OpenCode v1.4.3	✅ Fully working	Recommended for production
OpenCode v1.4.4 - v1.4.7	✅ Working (type update)	Update test mock type only
NAPI loading issue	✅ Cache issue, not loader bug	Clear cache if affected
Issue #20623	Open but root cause clarified	No code fix needed; clear cache resolves it
lancedb-opencode-pro v0.8.1	✅ Compatible with v1.4.3	Ready to use

Immediate Actions Required

For development: Update test mock type in test/regression/plugin.test.ts
For CI/CD: No changes needed after test mock update
For users: No action needed

Next Steps

Update test mock to use Effect.unit for ToolContext.ask()
Verify all tests pass with SDK 1.4.7
Release v0.8.3 with SDK 1.4.7 support

Last Verified: April 17, 2026
Tested On: OpenCode v1.4.3 (stable), v1.4.7 (type update only)
Status: Ready for SDK 1.4.7 with test mock update

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

OpenCode Compatibility & Troubleshooting Guide

📋 Version Compatibility Matrix

⚠️ OpenCode v1.4.4+ Compatibility (SDK Type Change)

Type Change: `ToolContext.ask()` Return Type

Error Details

Root Cause

Fix: Update Test Mock

Quick Fix Command

✅ OpenCode v1.4.3 Compatibility (Verified April 10, 2026)

🔍 Issue #20623 — Root Cause Clarification

Original Report

Author's Update: The Real Root Cause

Why v1.4.3 Works

🔴 If You See "Memory store unavailable"

Step 1: Clear the plugin cache (fixes most cases)

Step 2: Verify Ollama is accessible

Step 3: Check plugin installation

Step 4: Advanced — test native module loading directly

🔧 Solutions

Solution 1: Clear Plugin Cache (RECOMMENDED)

Solution 2: Upgrade to OpenCode v1.4.3

Solution 3: Downgrade to v1.3.7 (Legacy Workaround — Not Recommended)

📋 Version Compatibility Details

v1.3.14 SDK Changes

v1.4.0+ Breaking SDK Changes

v1.4.7 Type Change: ToolContext.ask()

📊 OpenCode SDK Version History (1.4.3 - 1.4.7)

Full Changelog

📚 Hook Stability Reference

🔍 Related Issues

📊 Troubleshooting Decision Tree

📚 Related Documentation

🎯 Summary

Immediate Actions Required

Next Steps

FilesExpand file tree

OPENCODE_COMPATIBILITY.md

Latest commit

History

OPENCODE_COMPATIBILITY.md

File metadata and controls

OpenCode Compatibility & Troubleshooting Guide

📋 Version Compatibility Matrix

⚠️ OpenCode v1.4.4+ Compatibility (SDK Type Change)

Type Change: ToolContext.ask() Return Type

Error Details

Root Cause

Fix: Update Test Mock

Quick Fix Command

✅ OpenCode v1.4.3 Compatibility (Verified April 10, 2026)

🔍 Issue #20623 — Root Cause Clarification

Original Report

Author's Update: The Real Root Cause

Why v1.4.3 Works

🔴 If You See "Memory store unavailable"

Step 1: Clear the plugin cache (fixes most cases)

Step 2: Verify Ollama is accessible

Step 3: Check plugin installation

Step 4: Advanced — test native module loading directly

🔧 Solutions

Solution 1: Clear Plugin Cache (RECOMMENDED)

Solution 2: Upgrade to OpenCode v1.4.3

Solution 3: Downgrade to v1.3.7 (Legacy Workaround — Not Recommended)

📋 Version Compatibility Details

v1.3.14 SDK Changes

v1.4.0+ Breaking SDK Changes

v1.4.7 Type Change: ToolContext.ask()

📊 OpenCode SDK Version History (1.4.3 - 1.4.7)

Full Changelog

📚 Hook Stability Reference

🔍 Related Issues

📊 Troubleshooting Decision Tree

📚 Related Documentation

🎯 Summary

Immediate Actions Required

Next Steps

Type Change: `ToolContext.ask()` Return Type