{"record":{"id":"1fb8a62bcc641b8a","repo":"headroomlabs-ai/headroom","slug":"headroom-opencode-transport-shim-loaded-without-he-1fb8a6","errorCode":null,"errorMessage":"Headroom OpenCode transport shim loaded without HEADROOM_OPENCODE_TRANSPORT_PROXY_URL","messagePattern":"Headroom OpenCode transport shim loaded without HEADROOM_OPENCODE_TRANSPORT_PROXY_URL","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"plugins/opencode/src/hook-shim.ts","lineNumber":21,"sourceCode":"// at headroom/providers/opencode/hook-shim/handler.js.\n//\n// transport.ts wraps `fetch`/`http`/`https` in the plugin's own process, but a\n// spawned Node child (an `npx` MCP server, `tokensave serve`, ...) is a fresh\n// process, so its traffic is only routed if this loader runs at that child's\n// startup via NODE_OPTIONS=--import. `shimImportSpecifier()` in transport.ts\n// resolves `../hook-shim/handler.js` next to the loaded entry, which is this\n// file in a wheel install.\n//\n// The checkout uses plugins/opencode/hook-shim/handler.js instead, which imports\n// the non-bundled `../dist/index.js`; pip installs have no node_modules, so this\n// variant inlines the transport. Without it shipped, the loader path did not\n// exist, so child-process routing was silently disabled for wheel installs\n// (before #2806 it crashed every Node child with ERR_MODULE_NOT_FOUND) (#2850).\nimport { installHeadroomTransport } from \"./transport.js\";\n\nconst proxyUrl = process.env.HEADROOM_OPENCODE_TRANSPORT_PROXY_URL;\nif (!proxyUrl) {\n  throw new Error(\n    \"Headroom OpenCode transport shim loaded without HEADROOM_OPENCODE_TRANSPORT_PROXY_URL\",\n  );\n}\n\ninstallHeadroomTransport({ proxyUrl });\n","sourceCodeStart":3,"sourceCodeEnd":27,"githubUrl":"https://github.com/headroomlabs-ai/headroom/blob/322425c43bffde1ed0b64fecf3cf5951565dd82b/plugins/opencode/src/hook-shim.ts#L3-L27","documentation":"Same guard as the built shim, but in the source variant plugins/opencode/src/hook-shim.ts used for wheel (pip) installs: it inlines the transport import and still requires HEADROOM_OPENCODE_TRANSPORT_PROXY_URL at module load. The comment history shows this path previously crashed children with ERR_MODULE_NOT_FOUND and then silently disabled routing; now it fails loudly when the env var is missing. Throwing at import time makes misconfiguration visible instead of silently unrouted traffic.","triggerScenarios":"Importing plugins/opencode/src/hook-shim.ts (pip/wheel install of the OpenCode plugin) without HEADROOM_OPENCODE_TRANSPORT_PROXY_URL set in that process's environment.","commonSituations":"pip-installed plugin loaded by OpenCode hooks in a shell where the variable was never exported; CI runners with a minimal env; switching from npm to pip install of headroom and forgetting the env setup step; hook config enabled for all projects but the var only set in one shell profile.","solutions":["Export the variable in the shell/profile that launches OpenCode: export HEADROOM_OPENCODE_TRANSPORT_PROXY_URL=http://127.0.0.1:8787","Put it in the OpenCODE project/user config env section or .env mechanism your launcher honors so all children inherit it","If some sessions intentionally run without the proxy, disable the hook there instead of loading the shim without the variable"],"exampleFix":"# before: pip-installed plugin loaded without the var\npip install headroom-ai && opencode  # shim throws on import\n\n# after\npip install headroom-ai\nexport HEADROOM_OPENCODE_TRANSPORT_PROXY_URL=http://127.0.0.1:8787\nopencode","handlingStrategy":"validation","validationCode":"// Validate env before the hook can load the source shim (pip/wheel installs)\nif (!process.env.HEADROOM_OPENCODE_TRANSPORT_PROXY_URL) {\n  console.error(\n    \"Skipping Headroom OpenCode transport: HEADROOM_OPENCODE_TRANSPORT_PROXY_URL is not set\"\n  );\n} else {\n  await import(\"./hook-shim.js\");\n}","typeGuard":"function hasTransportEnv(env: Record<string, string | undefined>): boolean {\n  return Boolean(env.HEADROOM_OPENCODE_TRANSPORT_PROXY_URL);\n}","tryCatchPattern":null,"preventionTips":["Set HEADROOM_OPENCODE_TRANSPORT_PROXY_URL in the same env mechanism that installs the pip package (shell profile, CI env block)","Treat the variable as required config for wheel installs — add it next to the pip install line in docs and Dockerfiles","In multi-project setups, only enable the OpenCode hook in projects whose environment defines the proxy URL"],"tags":["environment","configuration","opencode","plugin","pip"],"backgroundTag":null,"analyzedSha":"322425c43bffde1ed0b64fecf3cf5951565dd82b","analyzedAt":"2026-08-15T01:03:05.481Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}