vercel/ai · error · HarnessBridgeCapabilityUnsupportedError

The ACP implementation did not load the active harness-owned

Error message

The ACP implementation did not load the active harness-owned MCP tool catalog to revision ${catalog.revision} before the next prompt, so host tools cannot be exposed safely.

What it means

refreshHostToolCatalog verifies, within a timeout, that the ACP implementation loaded the harness-owned MCP tool catalog up to the current catalog revision before the next prompt. If it did not, the library throws HarnessBridgeCapabilityUnsupportedError because exposing host tools against a stale catalog would be unsafe.

Source

Thrown at packages/harness-acp/src/v1/bridge/refresh-host-tool-catalog.ts:54

  harnessId,
  timeoutMs,
}: {
  relay: Pick<HostToolRelay, 'updateCatalog' | 'waitForCatalogRefresh'>;
  tools: ReadonlyArray<HarnessV1BridgeToolWire>;
  harnessId: string;
  timeoutMs: number;
}): Promise<void> {
  const catalog = relay.updateCatalog({ tools });
  if (!catalog.changed && tools.length === 0) return;
  if (
    await relay.waitForCatalogRefresh({
      revision: catalog.revision,
      timeoutMs,
    })
  ) {
    return;
  }
  throw new HarnessBridgeCapabilityUnsupportedError({
    harnessId,
    message:
      'The ACP implementation did not load the active harness-owned MCP ' +
      `tool catalog to revision ${catalog.revision} before the next ` +
      'prompt, so host tools cannot be exposed safely.',
  });
}

View on GitHub (pinned to 69428b1f8b)

Solutions

Upgrade the ACP implementation to one that supports loading harness-owned MCP tool catalogs to the requested revision.
Increase timeoutMs if the agent reloads the catalog but slowly.
Check the agent's logs for MCP catalog-load failures and fix the underlying MCP server error.
Reduce catalog revision churn or ensure the catalog is stable before prompting.

Example fix

// before
await refreshHostToolCatalog({ agent, catalog, timeoutMs: 1000 }); // too short
// after
await refreshHostToolCatalog({ agent, catalog, timeoutMs: 30000 });

Defensive patterns

Strategy: retry

Validate before calling

const loaded = await agent.request('tools/catalogStatus', { revision: catalog.revision }).catch(() => null);
if (loaded?.revision !== catalog.revision) {
  throw new Error('Agent has not loaded the current tool catalog revision');
}

Try / catch

import { HarnessBridgeCapabilityUnsupportedError } from '...';
try {
  await refreshHostToolCatalog({ agent, catalog, timeoutMs });
} catch (error) {
  if (HarnessBridgeCapabilityUnsupportedError.isInstance?.(error)) {
    // degrade: run without host tools, or restart the agent and retry once
  }
  throw error;
}

Prevention

Use generous timeoutMs for catalog refresh relative to agent startup time.
Verify the agent version supports harness-owned MCP catalog loading before enabling host tools.
Avoid mutating the catalog immediately before prompts; refresh, await ack, then prompt.
Monitor agent logs for MCP server load failures.

When it happens

Trigger: The agent failed to reload/acknowledge the harness MCP tool catalog to catalog.revision within timeoutMs before the next prompt (ensureSession or promptAndRefreshInitialHostToolCatalog paths); slow or unresponsive agent; agent that ignores the catalog-update mechanism.

Common situations: Agent version lacking catalog-refresh support; agent busy or hung so the refresh times out; revision churn (frequent tool-catalog changes) outpacing the agent's reload; MCP server startup failure inside the agent.

Related errors

AI-assisted analysis of vercel/ai@69428b1f8b (2026-08-30). Data as JSON: /api/errors/d5aa5d95b9fb4f20. Report an issue: GitHub.