{"record":{"id":"052c37ca9e6ddd56","repo":"t8y2/dbx","slug":"dbx-pi-mcp-bridge-configuration-is-incomplete","errorCode":null,"errorMessage":"DBX Pi MCP bridge configuration is incomplete","messagePattern":"DBX Pi MCP bridge configuration is incomplete","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"crates/dbx-core/assets/pi-mcp-bridge.mjs","lineNumber":54,"sourceCode":"      typeof item.mimeType === \"string\"\n    ) {\n      result.push({ type: \"image\", data: item.data, mimeType: item.mimeType });\n    }\n  }\n  if (result.length === 0) {\n    result.push({ type: \"text\", text: \"\" });\n  }\n  return result;\n}\n\nexport default async function registerDbxMcpBridge(pi) {\n  const program = process.env[MCP_PROGRAM_ENV];\n  const readyFile = process.env[READY_FILE_ENV];\n  const args = parseJsonEnv(MCP_ARGS_ENV, []);\n  const enabledTools = new Set(parseJsonEnv(ENABLED_TOOLS_ENV, []));\n\n  if (!program || !readyFile || !Array.isArray(args) || enabledTools.size === 0) {\n    throw new Error(\"DBX Pi MCP bridge configuration is incomplete\");\n  }\n\n  const child = spawn(program, args, {\n    stdio: [\"pipe\", \"pipe\", \"pipe\"],\n    windowsHide: true,\n    env: process.env,\n  });\n  const pending = new Map();\n  let nextId = 1;\n  let stderr = \"\";\n  let closed = false;\n\n  child.stderr.setEncoding(\"utf8\");\n  child.stderr.on(\"data\", (chunk) => {\n    stderr = `${stderr}${chunk}`.slice(-16_384);\n  });\n\n  const rejectPending = (message) => {","sourceCodeStart":36,"sourceCodeEnd":72,"githubUrl":"https://github.com/t8y2/dbx/blob/c0390bff16418b651f4728520d99adf8ce48829a/crates/dbx-core/assets/pi-mcp-bridge.mjs#L36-L72","documentation":"registerDbxMcpBridge validates the bridge environment at startup and throws when MCP_PROGRAM_ENV, READY_FILE_ENV, MCP_ARGS_ENV (array), or ENABLED_TOOLS_ENV (non-empty set) are missing or empty. The bridge cannot function without a child program, readiness file, args, and at least one enabled tool.","triggerScenarios":"Host process launched without one or more of the required env vars; MCP args not a JSON array; enabled-tools list an empty array; program or readyFile empty strings.","commonSituations":"Forgot to export the env vars when embedding the bridge in the pi host; partial config after a rename of env var keys; empty tool list after disabling all tools; upgrade changed the env contract.","solutions":["Set all four env values: the MCP program path, ready-file path, a JSON array of args, and a non-empty JSON array of tool names","Verify with printenv in the same environment the bridge process runs in","Check for renamed env constants (MCP_PROGRAM_ENV/READY_FILE_ENV/MCP_ARGS_ENV/ENABLED_TOOLS_ENV) after upgrading"],"exampleFix":"// before\nexport DBX_PI_MCP_ENABLED_TOOLS='[]'\n// after\nexport DBX_PI_MCP_PROGRAM='node'\nexport DBX_PI_MCP_READY_FILE='/tmp/dbx-mcp.ready'\nexport DBX_PI_MCP_ARGS='[\"server.mjs\"]'\nexport DBX_PI_MCP_ENABLED_TOOLS='[\"search\",\"read\"]'","handlingStrategy":"validation","validationCode":"const required = ['DBX_PI_MCP_PROGRAM','DBX_PI_MCP_READY_FILE','DBX_PI_MCP_ARGS','DBX_PI_MCP_ENABLED_TOOLS'];\nconst missing = required.filter((k) => !process.env[k]);\nif (missing.length) throw new Error('missing env: ' + missing.join(','));\nif (!Array.isArray(JSON.parse(process.env.DBX_PI_MCP_ARGS))) throw new Error('MCP args must be a JSON array');\nif (JSON.parse(process.env.DBX_PI_MCP_ENABLED_TOOLS).length === 0) throw new Error('no tools enabled');","typeGuard":null,"tryCatchPattern":"try {\n  registerDbxMcpBridge(pi);\n} catch (e) {\n  console.error('Bridge startup failed:', e.message);\n  process.exit(1);\n}","preventionTips":["Set all four env vars before embedding the bridge","Keep a non-empty enabled-tools list","Re-check env var names after upgrades","printenv inside the actual process environment"],"tags":["configuration","env-var","mcp"],"backgroundTag":"missing-env-var","analyzedSha":"c0390bff16418b651f4728520d99adf8ce48829a","analyzedAt":"2026-09-05T23:05:10.900Z","contentChangedAt":"2026-09-05T23:05:10.900Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}