Repository navigation
plugins for V2: local plugin paths fail to load (file entries rejected, @opencode/plugin unresolvable) #49608
Description
Description
A local plugin cannot be loaded by following the documentation.
-
A
pluginsentry pointing at a.tsfile is rejected with
WARN "configured plugin path must be a directory", and the plugin never loads. The plugins
documentation shows exactly this form (./plugins/local,../shared/plugin.ts,
/absolute/path/plugin.ts,file:///home/me/plugins/local). -
An entry pointing at a directory (or a plugin discovered under
.opencode/plugins/) is found and
imported, but loading fails because the documented import is not resolvable:level=INFO message="loading plugin" id=…/mi-plugin entrypoint=file:///…/mi-plugin/index.ts level=WARN message="failed to load plugin" cause="Cause([Die(ResolveMessage: Cannot find package '@opencode/plugin' imported from …\mi-plugin\index.ts)])"This happens with both loading paths (config entry and discovery). It only works if the plugin
directory ships its ownnode_modules.
In both cases the failure is silent outside the log — no error in the session, no hint in the TUI —
so the only visible symptom is that the plugin's tools and hooks do not exist.
Plugins
None configured globally. The reproductions use a single project entry in opencode.jsonc and a
directory under .opencode/plugins/.
OpenCode version
2.0.3 (@opencode/cli installed globally with npm)
Steps to reproduce
A. plugins entry pointing at a .ts file
-
Create a local plugin with a single default export:
export default { id: "x", setup() {} }. -
Configure the entry:
{ "plugins": ["C:/absolute/path/mi-plugin/index.ts"] }. -
Start any session in that project (
opencode run --standalone --print-logs --log-level info).Log:
level=WARN message="configured plugin path must be a directory" target=C:/absolute/path/mi-plugin/index.ts
B. Directory entry or .opencode/plugins/ discovery importing @opencode/plugin
-
Create
<project>/.opencode/plugins/mi-plugin/index.ts:import { Plugin } from "@opencode/plugin" export default Plugin.define({ id: "mi-plugin", async setup() {}, })
-
Start a session in that project.
The module is found, then loading fails with the
Cannot find package '@opencode/plugin'cause above.
Screenshot and/or share link
N/A — both failures are only visible in the server log; the log lines are quoted above.
Operating System
Windows 10 Enterprise LTSC 10.0.19044 (x64)
Terminal
Not applicable: reproduced headlessly with opencode run --standalone from PowerShell 5.1
(TERM=xterm-256color, TERM_PROGRAM unset, %COMSPEC% = cmd.exe).
Additional context (not part of the form):
- Workarounds that work: export a plain object (
export default { id, setup }) instead of
Plugin.define; or run an install inside the plugin directory so@opencode/pluginresolves
locally (@opencode/plugin@2.0.5is published on npm). - Why this matters: the first case is a documentation/behaviour mismatch, and the second blocks
every local (non-published) plugin that follows the documented import. Both fail silently, which
makes them expensive to diagnose. - Notes: tested with the path written as
C:/…andC:\…;opencode plugin listdoes not load
project plugins, so it cannot be used to verify. Reproduced consistently on 2.0.3.
Activity
[-]plugins: local plugin paths fail to load (file entries rejected, @opencode/plugin unresolvable)[/-][+]plugins for V2: local plugin paths fail to load (file entries rejected, @opencode/plugin unresolvable)[/+]github-actions commentedon Sep 17, 2026
This issue might be a duplicate of existing issues. Please check:
.tsfiles andfile://URIs) are silently dropped with "configured plugin path must be a directory" — same as your issue A..tsplugins fail to load on Windows with aCannot find module/Cannot find packageerror in the compiled binary — closely related to your issue B.If your report adds new information (e.g. the
@opencode/pluginpackage resolution failure being distinct from the mtime query-string issue in #42763, or the.opencode/plugins/discovery path being affected), please note that in those issues or confirm that this is a separate root cause worth tracking independently.wppqqppq commentedon Oct 13, 2026
Data point for the second half of this report, on opencode 2.0.27 (latest, macOS): a plugin loaded by discovery from
.opencode/plugins/does resolveimport { Plugin } from "@opencode/plugin"with nonode_modulesanywhere in scope.Isolated reproduction — session cwd
/tmp/oc-probe, plugin at/tmp/oc-probe/.opencode/plugins/probe.ts:There is no
node_modulesin/tmp/oc-probe,/tmp, or/, and no reponode_modulesis an ancestor, so only a host-provided module could satisfy the import. Result:No
failed to load plugin, noCannot find package '@opencode/plugin'.So on 2.0.27 the host does provide
@opencode/pluginto discovery-loaded plugins. TheCannot find packagefailure you saw may be specific to the config-directory entry path, or a platform/packaging difference (your log paths look Windows-flavoured). The first half of your report —pluginsentries pointing at a.tsfile rejected withconfigured plugin path must be a directorywhile the docs advertise exactly that form — reproduces identically; details on #46551.opencodejr commentedon Oct 28, 2026
Thanks for the detailed report. Both problems you describe are already tracked:
.tsfile entry rejected withconfigured plugin path must be a directoryis the same as plugin: configured local plugin file paths silently dropped since #46105 #46551.Cannot find package '@opencode/plugin'failure for directory entries and.opencode/plugins/discovery is the same as plugins: local plugins cannot resolve "@opencode/plugin" import (2.0.12) #50434.Possible duplicates and related issues, ordered from most to least likely:
pluginsentries that point at a file are dropped, and only this warning is logged. The plugins docs have since been updated to show directory paths (../shared/plugin,/absolute/path/plugin) instead of.tsfiles.import { Plugin } from "@opencode/plugin"fail to resolve it, whether discovered or configured. It has been confirmed by several users, including on Windows. A comment there reports that the same setup loads on the latest release (2.2.0), so upgrading from 2.0.3 may already fix this part.pluginsare silently never loaded; plugin import failures produce no log #58647: related. It covers plugin paths that are dropped without any log line (see also fix(core): log skipped plugin discovery #59707).Until then, point the entry at the plugin's directory, which needs an
index.ts/index.js, rather than at the file.The bot will close this issue as a duplicate in 1 day unless you reply explaining how your problem is different.
opencodejr commentedon Oct 29, 2026
We haven't heard back in the last day, so I'm closing this as a duplicate. Both problems you reported are already tracked:
pluginsentry that points at a.ts/.jsfile is dropped, and the only sign isconfigured plugin path must be a directoryin the log. The docs now show directory paths instead of file paths.@opencode/pluginfail withCannot find package '@opencode/plugin'. A comment there says the same setup loads on 2.2.0, so upgrading from 2.0.3 may fix this part.Please follow those issues for updates. Your Windows reproduction would be a useful comment on either of them. If your problem turns out to be different, reply here and we can reopen.