vercel/ai · error · Error

ACP credentialEnv and credentialBrokering must be configured

Error message

ACP credentialEnv and credentialBrokering must be configured together.

What it means

createACPV1, the v1 implementation behind createACP, performs the same pair-validation as the outer factory: credentialEnv and credentialBrokering must both be present or both absent. The check exists in both layers so direct callers of the v1 path cannot bypass the invariant; providing only one makes credential injection ambiguous and is rejected.

Source

Thrown at packages/harness-acp/src/v1/acp-v1-harness.ts:142

  startupTimeoutMs,
  clientApp,
  lifecycleStateSchema,
}: {
  settings: ACPV1Settings;
  builtinTools: TBuiltinTools;
  port?: number;
  portEndpoint?: HarnessV1PortEndpoint;
  startupTimeoutMs?: number;
  clientApp: ACPClientApp;
  lifecycleStateSchema: NonNullable<
    HarnessV1<TBuiltinTools>['lifecycleStateSchema']
  >;
}): HarnessV1<TBuiltinTools> {
  if (
    (settings.credentialEnv == null) !==
    (settings.credentialBrokering == null)
  ) {
    throw new Error(
      'ACP credentialEnv and credentialBrokering must be configured together.',
    );
  }
  if (
    settings.mcpServers != null &&
    Object.prototype.hasOwnProperty.call(
      settings.mcpServers,
      'ai-sdk-harness-tools',
    )
  ) {
    throw new Error(
      'ACP MCP server name "ai-sdk-harness-tools" is reserved for HarnessAgent tools.',
    );
  }
  if (!HARNESS_ID_REGEXP.test(settings.harnessId)) {
    throw new Error(
      `ACP harnessId must be a stable kebab-case identifier; received ${JSON.stringify(settings.harnessId)}.`,
    );

View on GitHub (pinned to 69428b1f8b)

Solutions

1. Supply both credentialEnv and credentialBrokering together.
2. Omit both if credential brokering is not needed.
3. Ensure conditional settings construction keeps the fields consistent (spread both or neither).

Example fix

// before
createACP({ credentialBrokering: { mode: 'sandbox' } }); // throws
// after
createACP({
  credentialEnv: { DB_URL: '...' },
  credentialBrokering: { mode: 'sandbox' },
});

function validateCredentialPair(settings: { credentialEnv?: unknown; credentialBrokering?: unknown }): void {
  if ((settings.credentialEnv == null) !== (settings.credentialBrokering == null)) {
    throw new Error('credentialEnv and credentialBrokering must be set together.');
  }
}

When it happens

Trigger: Reaching the v1 harness creation (via createACP or wrappers) with settings where exactly one of credentialEnv / credentialBrokering is set (including one being explicitly undefined while the other is provided).

Common situations: Programmatically constructing settings where one field is conditionally spread and the other is not; partial refactors; wrappers that fill in only one of the pair.

Related errors

• ACP credentialEnv and credentialBrokering must be configured
• ACP MCP server ${JSON.stringify(name)} must be configured wi
• ACP profile data must resolve to an object.
• ACP source.packageJson must not be empty.
• ACP source.pnpmLockYaml must not be empty.

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