{"record":{"id":"3be66097d3796c31","repo":"headroomlabs-ai/headroom","slug":"headroom-opencode-transport-shim-loaded-without-he-3be660","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/hook-shim/handler.js","lineNumber":5,"sourceCode":"import { installHeadroomTransport } from \"../dist/index.js\";\n\nconst proxyUrl = process.env.HEADROOM_OPENCODE_TRANSPORT_PROXY_URL;\nif (!proxyUrl) {\n  throw new Error(\"Headroom OpenCode transport shim loaded without HEADROOM_OPENCODE_TRANSPORT_PROXY_URL\");\n}\n\ninstallHeadroomTransport({ proxyUrl });\n","sourceCodeStart":1,"sourceCodeEnd":9,"githubUrl":"https://github.com/headroomlabs-ai/headroom/blob/322425c43bffde1ed0b64fecf3cf5951565dd82b/plugins/opencode/hook-shim/handler.js#L1-L9","documentation":"The OpenCode transport shim (built handler.js) is a side-effect-only module: it reads HEADROOM_OPENCODE_TRANSPORT_PROXY_URL at import time and throws if it is unset, because installing the transport without a proxy target is a programming error. Since it throws during module evaluation, the whole Node child process load fails, not just one request.","triggerScenarios":"Any mechanism that loads plugins/opencode/hook-shim/handler.js (OpenCode hook/plugin loader, a wheel install's shim path) in a Node process where HEADROOM_OPENCODE_TRANSPORT_PROXY_URL is not set — unset, empty string, or set only in a parent shell that did not export it.","commonSituations":"Env var set with 'VAR=value' instead of 'export VAR=value'; child process spawned with a sanitized env; hook registered globally so it loads in every OpenCode session, including ones started without the proxy; name typo in the variable.","solutions":["Set and export the variable before starting OpenCode / the process that loads the shim: export HEADROOM_OPENCODE_TRANSPORT_PROXY_URL=http://127.0.0.1:8787","Ensure child processes inherit it (pass env: { ...process.env } when spawning)","If the shim should not load in some contexts, gate the hook registration on the env var being present rather than letting the module throw"],"exampleFix":"# before\nHEADROOM_OPENCODE_TRANSPORT_PROXY_URL=http://127.0.0.1:8787 opencode  # not exported to children in some spawn paths\n\n# after\nexport HEADROOM_OPENCODE_TRANSPORT_PROXY_URL=http://127.0.0.1:8787\nopencode","handlingStrategy":"validation","validationCode":"// Gate before anything can import the shim\nconst proxyUrl = process.env.HEADROOM_OPENCODE_TRANSPORT_PROXY_URL;\nif (!proxyUrl) {\n  throw new Error(\n    \"HEADROOM_OPENCODE_TRANSPORT_PROXY_URL is not set — the OpenCode transport shim must not be loaded\"\n  );\n}\n// only now safe to import / register the hook\nimport(\"./hook-shim/handler.js\");","typeGuard":"function shimEnvPresent(env: NodeJS.ProcessEnv): env is NodeJS.ProcessEnv & {\n  HEADROOM_OPENCODE_TRANSPORT_PROXY_URL: string;\n} {\n  return typeof env.HEADROOM_OPENCODE_TRANSPORT_PROXY_URL === \"string\"\n    && env.HEADROOM_OPENCODE_TRANSPORT_PROXY_URL.length > 0;\n}","tryCatchPattern":null,"preventionTips":["Export the variable in the shell/profile that launches the process: export HEADROOM_OPENCODE_TRANSPORT_PROXY_URL=http://127.0.0.1:8787","When spawning children that load the shim, forward the full environment (env: { ...process.env })","Conditionally register the OpenCode hook only when the env var is present, so proxy-less sessions never import the shim"],"tags":["environment","configuration","opencode","plugin","module-load"],"backgroundTag":null,"analyzedSha":"322425c43bffde1ed0b64fecf3cf5951565dd82b","analyzedAt":"2026-08-15T01:03:05.481Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}