t8y2/dbx · error · Error

DBX Pi MCP bridge configuration is incomplete

Error message

DBX Pi MCP bridge configuration is incomplete

What it means

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.

Source

Thrown at crates/dbx-core/assets/pi-mcp-bridge.mjs:54

      typeof item.mimeType === "string"
    ) {
      result.push({ type: "image", data: item.data, mimeType: item.mimeType });
    }
  }
  if (result.length === 0) {
    result.push({ type: "text", text: "" });
  }
  return result;
}

export default async function registerDbxMcpBridge(pi) {
  const program = process.env[MCP_PROGRAM_ENV];
  const readyFile = process.env[READY_FILE_ENV];
  const args = parseJsonEnv(MCP_ARGS_ENV, []);
  const enabledTools = new Set(parseJsonEnv(ENABLED_TOOLS_ENV, []));

  if (!program || !readyFile || !Array.isArray(args) || enabledTools.size === 0) {
    throw new Error("DBX Pi MCP bridge configuration is incomplete");
  }

  const child = spawn(program, args, {
    stdio: ["pipe", "pipe", "pipe"],
    windowsHide: true,
    env: process.env,
  });
  const pending = new Map();
  let nextId = 1;
  let stderr = "";
  let closed = false;

  child.stderr.setEncoding("utf8");
  child.stderr.on("data", (chunk) => {
    stderr = `${stderr}${chunk}`.slice(-16_384);
  });

  const rejectPending = (message) => {

View on GitHub (pinned to c0390bff16)

Solutions

1. 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
2. Verify with printenv in the same environment the bridge process runs in
3. Check for renamed env constants (MCP_PROGRAM_ENV/READY_FILE_ENV/MCP_ARGS_ENV/ENABLED_TOOLS_ENV) after upgrading

Example fix

// before
export DBX_PI_MCP_ENABLED_TOOLS='[]'
// after
export DBX_PI_MCP_PROGRAM='node'
export DBX_PI_MCP_READY_FILE='/tmp/dbx-mcp.ready'
export DBX_PI_MCP_ARGS='["server.mjs"]'
export DBX_PI_MCP_ENABLED_TOOLS='["search","read"]'

const required = ['DBX_PI_MCP_PROGRAM','DBX_PI_MCP_READY_FILE','DBX_PI_MCP_ARGS','DBX_PI_MCP_ENABLED_TOOLS'];
const missing = required.filter((k) => !process.env[k]);
if (missing.length) throw new Error('missing env: ' + missing.join(','));
if (!Array.isArray(JSON.parse(process.env.DBX_PI_MCP_ARGS))) throw new Error('MCP args must be a JSON array');
if (JSON.parse(process.env.DBX_PI_MCP_ENABLED_TOOLS).length === 0) throw new Error('no tools enabled');

try {
  registerDbxMcpBridge(pi);
} catch (e) {
  console.error('Bridge startup failed:', e.message);
  process.exit(1);
}

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

• Invalid ${name}: ${error.message}
• DBX_PUBLIC_BASE_PATH contains invalid characters
• Invalid DBX Web MCP configuration
• Agent runtime thread limits must be positive
• H2 JDBC driver rejected URL: " + buildJdbcUrl(params)

AI-assisted analysis of t8y2/dbx@c0390bff16 (2026-09-05). Data as JSON: /api/errors/052c37ca9e6ddd56. Report an issue: GitHub.