bug: plugin fails to load in OpenCode with "path must be a string or a file descriptor" / "Received an instance of Object"

[imaadd05]

Problem

Loading the ponytail OpenCode plugin (@dietrichgebert/ponytail, installed via "plugin": ["@dietrichgebert/ponytail"] in opencode.json) fails at plugin-load time. OpenCode logs:

message="failed to load plugin" path=@dietrichgebert/ponytail error="path must be a string or a file descriptor"

and, in later runs (same install, no config change), a differently-worded variant of what looks like the same underlying failure:

message="failed to load plugin" path=@dietrichgebert/ponytail error="The \"path\" argument must be of type string or an instance of Buffer or URL. Received an instance of Object"

Environment

• @dietrichgebert/ponytail 4.8.4 (installed via OpenCode's git/npm plugin loader, ~/.cache/opencode/packages/@dietrichgebert/ponytail)
• OpenCode 1.17.18 (a downstream fork, but this is plugin-loading, not fork-specific behavior)
• Node v26.4.0 / Bun 1.3.14, macOS (Darwin 25.5.0, arm64)

What I ruled out

I dug into this while diagnosing an unrelated OpenCode bug and don't want to leave you without a lead, so here's what I checked:

• This looked like it could be a recurrence of Bug: Test suite fails on Node.js versions < 20.11.0 due to import.meta.dirname usage #156 (import.meta.dirname unavailable → path.join(undefined, ...)), but that pattern is fully gone from the 4.8.4 source (grep -rn "import.meta.dirname" over the installed package returns nothing), and the second error text explicitly says "Received an instance of Object", not undefined — so it's a different failure: something is passing a non-path object where fs/path expects a string/Buffer/URL.
• Manually import()-ing .opencode/plugins/ponytail.mjs and invoking the default export directly with { client: undefined } succeeds fine and returns all three hooks (config, experimental.chat.system.transform, command.execute.before) — so the crash isn't in the module's top-level factory body executing in isolation. It must be triggered by something OpenCode's real plugin-loader passes in (e.g. the actual PluginInput/client shape), which I didn't have on hand to fully reproduce outside the running app.
• Notably, despite this load failure, the plugin's experimental.chat.system.transform hook still appears to fire successfully on chat turns (it's what caused the OpenCode-side bug I was diagnosing) — so whatever throws seems to happen either during a different hook invocation, or asynchronously after registration succeeds, rather than blocking config load entirely.

Suggested next step

Since the crash didn't reproduce with a bare {client: undefined} input, the likely spot is code paths that consume more of PluginInput than just client — worth auditing anywhere a path.*/fs.* call could receive a client/config/URL-like object instead of a string (e.g. if a value from OpenCode's client/config object ever flows into a path.join/fs.readFileSync call unchecked).

Happy to share the exact opencode.json plugin config or more log context if useful.

[kalepail]

Root cause found, and the good news is the fix is already in main — it just hasn't been published to npm.

Root cause

OpenCode's loader calls every export as a plugin factory. From the 1.18.1 binary:

function sk($){ let Z=new Set,Q=[]; for(let Y of Object.values($)){ ... let X=nk(Y);
  if(!X)throw TypeError("Plugin export is not a function"); Q.push(X)} return Q}
async function ak($,Z,Q){ let Y=nM($.mod,$.spec,"server","detect");
  if(Y){ ... return}
  for(let X of sk($.mod)) Q.push(await X(Z,$.options))   // <-- every export, called with (input, options)
}

Object.values(mod) → so parseCommandFile is invoked as a factory with OpenCode's context object, hits fs.readFileSync(<object>), and throws — aborting the whole module's load.

That is exactly what #301 ("stop exporting parseCommandFile from plugin module") already diagnosed and fixed.

Why it's still happening

The fix is in main but not in the published tarball:

# git main (14a0d79)
$ grep '^export' .opencode/plugins/ponytail.mjs
46:export default async ({ client } = {}) => {

# npm @dietrichgebert/ponytail@4.8.4  <- what OpenCode installs
$ grep '^export' .opencode/plugins/ponytail.mjs
45:export function parseCommandFile(filePath) {
54:export default async ({ client } = {}) => {

4.8.4 was published 2026-06-29; #301 merged 2026-07-09. No release since, so every npm consumer still gets the pre-fix module. A patch release should close this — no code change needed.

Also explains the two error strings in the report: same throw, Bun's wording (path must be a string or a file descriptor) vs Node's (Received an instance of Object).

Confirmation

Reproduced and fixed on OpenCode 1.18.1 / macOS 15.5 arm64:

# npm 4.8.4 -> fails (both "@dietrichgebert/ponytail" and the local .mjs path form)
message="failed to load plugin" path=... error="path must be a string or a file descriptor"

# pinned to git main -> loads clean, exports: [ 'default' ]
$ npm install "github:DietrichGebert/ponytail#14a0d79"

With main, the plugin loads and experimental.chat.system.transform injects the ruleset at the active level, and config registers all 6 commands + the skills path.

Workaround until a release

Install from git rather than npm:

// ~/.config/opencode/opencode.json
{ "plugin": ["./node_modules/@dietrichgebert/ponytail/.opencode/plugins/ponytail.mjs"] }

npm install "github:DietrichGebert/ponytail#14a0d79" --save   # in ~/.config/opencode

(Or, staying on npm, a shim re-exporting only the default works: export { default } from '@dietrichgebert/ponytail';)

One adjacent note: the bare {"plugin": ["@dietrichgebert/ponytail"]} form makes OpenCode resolve its own copy from npm into ~/.cache/opencode/node_modules, so it will keep hitting the broken 4.8.4 regardless of what's in the local node_modules.

@imaadd05's "the transform hook still appears to fire" note is worth a second look — I didn't see hooks fire on a failed load in 1.18.1.