vercel/ai · error · Error

ACP credentialEnv and credentialBrokering must be…

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.

Solutions

Supply both credentialEnv and credentialBrokering together.
Omit both if credential brokering is not needed.
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' },
});

Defensive patterns

Strategy: validation

Validate before calling

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.');
  }
}

Prevention

Construct credential settings from one source object and spread both fields together.
Add schema/type-level coupling (single options object) to keep the pair aligned.
Test settings construction with both present and both absent cases.

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

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

Appendix: 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)