vercel/ai · error · Error

ACP credentialEnv and credentialBrokering must be configured

Error message

ACP credentialEnv and credentialBrokering must be configured together.

What it means

createACP validates that the optional credentialEnv and credentialBrokering settings are supplied as a pair. These two options together define how sandbox credentials are exposed to the agent process; providing only one leaves credential brokering half-configured, so the harness rejects the settings up front rather than failing later at runtime.

Source

Thrown at packages/harness-acp/src/acp-harness.ts:125

    .optional(),
  restoration: z
    .object({
      method: z.enum(['resume', 'load']),
    })
    .optional(),
  initialGuidanceApplied: z.boolean().optional(),
  instructionsFingerprint: z.string().optional(),
  skillsDirectory: z.string().optional(),
});

export function createACP<TBuiltinTools extends ToolSet = {}>(
  settings: ACPHarnessSettings<TBuiltinTools>,
): 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.',
    );
  }
  const version = (settings as { readonly version?: string }).version ?? 'v1';
  switch (version) {
    case 'v1': {
      const clientApp = settings.clientApp ?? ACP_CLIENT_APP;

View on GitHub (pinned to 69428b1f8b)

Solutions

1. Add the matching credentialBrokering configuration alongside credentialEnv.
2. If brokering is not intended, remove credentialEnv (or set both to undefined) so the pair is consistent.
3. Check the wrapper factory you call (createCodexACP etc.) for defaults that may inject one option without the other.

Example fix

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

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: Calling createACP (or a wrapper like createCodexACP, createCursorACP, claudeCodeACPHarness) with settings that set credentialEnv but not credentialBrokering, or credentialBrokering but not credentialEnv.

Common situations: Copying a config snippet that only showed one of the two options; removing brokering config during refactor while leaving credentialEnv; wiring sandbox credential injection incrementally and forgetting the second half.

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/3c42ddf1ac3da394. Report an issue: GitHub.