plugin: configured local plugin file paths silently dropped since #46105 #46551

Activity

1. github-actions

   assigned

   jlongster

   on Sep 1, 2026
2. RaviTharuma commented on Sep 12, 2026

   

   RaviTharuma

   on Sep 12, 2026

   More actions

   Adding a data point on a neighbouring branch of the same resolver, in case it's useful to fix together.

   A configured plugin path that points to a non-existent directory produces no diagnostic at all — not even the WARN this issue describes for file paths. Verified on 1.18.30, same machine, same config shape:

   Config entry	Diagnostic
   /tmp/pluginrepro/nope.js (this issue)	WARN line
   ./plugins/vendor/does-not-exist-anywhere-0.0.1	none

   $ opencode run --print-logs 'hi' 2>&1 | grep -c 'does-not-exist-anywhere'
   0
   

   So the file branch is at least observable via --print-logs, while the missing-directory branch is completely silent. Your point that "silently losing plugins on upgrade is the worst outcome" applies with full force here: in my case it silently disabled a provider and every agent bound to it fell through to a fallback tier for hours before surfacing an unrelated-looking ProviderModelNotFoundError.

   Filed separately as #48577 since it's a distinct branch, but if you're already touching source.ts for this, both cases likely want the same treatment.
3. wppqqppq commented on Oct 13, 2026

   

   wppqqppq

   on Oct 13, 2026

   More actions

   Confirming this still reproduces on the latest release, not only on a source build — opencode 2.0.27 (npm view @opencode/cli version → 2.0.27). The entry is dropped with exactly this warning and the plugin is skipped silently (no msg="loading plugin" line, no other diagnostic).

   Every file form fails on 2.0.27:

   plugins entry	result
   "plugin": ["/Users/me/rtk_dev/rtk.ts"] (legacy key)	WARN configured plugin path must be a directory
   "plugins": ["/Users/me/rtk_dev/rtk.ts"]	same
   "plugins": ["./rtk.ts"]	same
   "plugins": ["file:///Users/me/rtk_dev/rtk.ts"]	same
   "plugins": ["/Users/me/rtk_dev/plugin.js"] (.js, not .ts)	same

   So it is neither .ts-specific nor limited to the new key.

   What works on 2.0.27:

   • Discovery: .opencode/plugins/<any-name>.ts loads and runs — including a symlink placed in that directory. Verified end-to-end: the loaded plugin's execute.before hook rewrote a shell command (ls -la package.json executed as rtk ls -la package.json, per message="spawning process" command=/bin/zsh args=["-c","rtk ls -la package.json"]).
   • A config entry pointing at a directory, but only with a root index.ts — see plugins: local plugin directory ignores package.json main and is silently skipped without a root entrypoint #52300 (package.json main is ignored: a directory holding package.json with main → plugin.ts, plus plugin.ts, and no index.ts, loads nothing).

   The docs still list ../shared/plugin.ts and /absolute/path/plugin.ts under plugins (https://opencode.ai/v2/docs/plugins/), so the doc/behaviour mismatch reported here is still live at the latest release.
4. opencodejr commented on Oct 28, 2026

   

   opencodejrBot

   on Oct 28, 2026

   More actions

   Thanks for the detailed write-up and the workaround. You were right that the docs and the loader disagreed when you filed this. Since then the plugins docs have been updated (#58280) to match the code. They now show only local plugin directories and say: "Configured local paths must be directories. A path to a single file is skipped." So dropping file entries is the intended v2 behaviour, and I'm treating this as a feature request with two parts:

   • accept a single file as a configured plugin entrypoint again, and/or
   • when a configured plugin is skipped, report it clearly (for example as a failed plugin or a visible warning) instead of only a WARN log line, so plugins don't silently disappear after an upgrade.

   Maintainers will consider it. Until then, point the entry at the plugin directory, with an index.js/server.js at its root or a package.json with name and exports, as you found.

   Related issues:

   • plugins for V2: local plugin paths fail to load (file entries rejected, @opencode/plugin unresolvable) #49608: a later report of the same file-path rejection
   • Plugins listed by absolute path in plugins are silently never loaded; plugin import failures produce no log #58647: absolute-path directory entries that are silently never loaded
   • fix(plugin): report configured plugin directories without an entrypoint #58767: an open PR that reports configured directories without an entrypoint as failed instead of silently dropping them
   • plugins: local plugin directory ignores package.json main and is silently skipped without a root entrypoint #52300, plugin: local directory plugin loads via package.json exports instead of index.js #59859: how local plugin directories choose their entrypoint