Skip to content

Latest commit

 

History

History
117 lines (88 loc) · 4.85 KB

troubleshooting.md

File metadata and controls

117 lines (88 loc) · 4.85 KB

Troubleshooting

On DSH: the odf-gates entry must only inject services the profile provides — injecting a missing service pends the entire plugin at boot (one stderr line, then silence). df install-dsh handles this per profile. Details: dsh.md.

Plugin fails to load: Duplicate plugin ID

Each project must register the plugin exactly once. Plugin arrays merge across config files (global opencode.jsonc, project ./opencode.jsonc, ./.opencode/opencode.json[c]), so a second entry in another file — even one pointing at a different path of the same repo such as dist/ — loads the same plugin ID twice and the duplicate fails. Check all three locations, and verify with:

opencode api get "/api/plugin?location[directory]=/path/to/project"

(The server log only shows harmless loading plugin lines for both entries — the API view is the one that tells the truth.)

TUI commands (/df-status, /df-help) never load

Point the entry at the repository root, not at dist/ directly: a bare directory without package.json/exports resolves only the server part. One root entry loads every part (server via dist/adapters/opencode/index.js, TUI via tui.tsx, resolved through the exports map).

Stale version after switching sources

OpenCode caches downloaded plugins in ~/.cache/opencode/packages/opencode-dev-framework*/. If you previously loaded a published version and then switch to a local source, clear that cache so OpenCode does not reuse the old build:

rm -rf ~/.cache/opencode/packages/opencode-dev-framework*

After every source change, rebuild — OpenCode loads the compiled dist/ output:

npm run build

Rebuilt but behavior unchanged (stale serve backend)

Plugin code runs in the shared opencode serve backend, not in your terminal/TUI process — restarting the client alone reuses the old server, so a rebuilt dist/ sits unread and new behavior silently never fires. After every plugin upgrade or rebuild, restart the serve backend so new and continued sessions pick up the new code.

Version matrix

Requires OpenCode v2.x (@opencode/plugin ^2) — tested on v2.0.26 and v2.2.0. On v1.18.18–1.18.31 use the v1 branch of this plugin (plugin key). The ./tui companion (/df-status and /df-help modals) is auto-discovered from the npm entry on v2 — no separate tui.json needed.

Diagnosing a red tree without triggering fixes

Under standard/strict, a red tree at the idle boundary continues the session until the cause is fixed — even if you asked for a report-only diagnosis (see Blocked gate, fix, pass). That is the documented price of a blocking profile, not a bug. Your options:

  • Call dev_framework_verify directly mid-turn for the report, then close the session yourself — the verdict is pure report, but the continuation still fires if you let the turn go idle on the red tree.
  • Drop to advisory for the session (/df-profile advisory) and flip back after — the gate reports instead of blocking. This is the only true look-without-touching.
  • Do nothing: if the failure is identical with no new edits across three evaluations, the gate stands down early on zero progress instead of spending the rest of gate.max_blocks. Bounded either way, but the early stop saves the wasted continuations.

Files you deleted mid-session

Lint steps skip tracked files that no longer exist — a missing file can never fail the gate. But a deletion is still a real change: typecheck and test steps run, because removing a file can break its dependents, and the clean pass is cached so the gate does not re-run it every idle. If your gate ever cites a file you already deleted, update the plugin — that was a bug in older versions, not your tree.

Still stuck

Every gate evaluation is logged as JSON lines: OPENCODE_DEV_FRAMEWORK_LOG_FILE overrides the location, otherwise the default is ~/.local/share/opencode-dev-framework/opencode-dev-framework.log ($XDG_DATA_HOME when set; ~/Library/Logs on macOS; %LOCALAPPDATA% on Windows). Grep it for verdicts:

grep -o '"reason":"[a-z]*"' ~/.local/share/opencode-dev-framework/opencode-dev-framework.log \
  | sort | uniq -c

The file rotates at 5 MB with one backup (.log.1), so worst case is 10 MB — history depth is thousands of evaluations.

Run a private server with the plugin trace on and read the log:

OPENCODE_DEV_FRAMEWORK_LOG_FILE=/tmp/odf.log opencode run --standalone --print-logs

OPENCODE_DEV_FRAMEWORK_LOG_LEVEL (default debug) sets the minimum level that reaches stderr and the file — raise it to warn to silence routine info/debug lines. Unknown values fall back to debug.

Plugin code runs in the opencode serve backend, not in your terminal process — a variable exported only in the TUI shell never reaches it.