ACP authentication method ${JSON.stringify(methodId)} is not

Error message

ACP authentication method ${JSON.stringify(methodId)} is not advertised by the agent. Advertised methods: ${advertised}.

What it means

assertACPAuthenticationMethod validates, after ACP initialization, that the auth method id passed to authenticate() was actually advertised by the agent in its initialize response (initialization.authMethods). The library throws this to prevent authenticating with a method the agent cannot perform. The error message includes the requested method id and the full list of advertised method ids for debugging.

Source

Thrown at packages/harness-acp/src/v1/bridge/protocol-configuration.ts:106

}): void {
  if (initialization.protocolVersion !== requested) {
    throw new Error(
      `ACP protocol negotiation failed: requested v${requested}, agent selected v${initialization.protocolVersion}.`,
    );
  }
}

export function assertACPAuthenticationMethod({
  initialization,
  methodId,
}: {
  initialization: ACPInitializeResult;
  methodId: string;
}): void {
  if (!initialization.authMethods?.some(method => method.id === methodId)) {
    const advertised =
      initialization.authMethods?.map(method => method.id).join(', ') || 'none';
    throw new Error(
      `ACP authentication method ${JSON.stringify(methodId)} is not advertised by the agent. Advertised methods: ${advertised}.`,
    );
  }
}

function mergeRecords({
  left,
  right,
}: {
  left: Readonly<Record<string, unknown>>;
  right: Readonly<Record<string, unknown>>;
}): Readonly<Record<string, unknown>> {
  const result: Record<string, unknown> = { ...left };
  for (const [key, value] of Object.entries(right)) {
    const previous = result[key];
    result[key] =
      isRecord(previous) && isRecord(value)
        ? mergeRecords({ left: previous, right: value })

View on GitHub (pinned to 69428b1f8b)

Solutions

Log or inspect initialization.authMethods after connecting and pick one of the advertised ids for authenticate().
Update the harness/bridge configuration to use the method id the current agent version advertises.
Fix typos or stale ids in the auth configuration (method ids are exact string matches).
If the agent advertises no methods ('none'), fix the agent side or use an auth path that does not require ACP authenticate.

Example fix

// before
await bridge.authenticate({ methodId: 'oauth2' });
// after
const { initialization } = await bridge.initialize();
const methodId = initialization.authMethods?.[0]?.id;
if (methodId) await bridge.authenticate({ methodId });

Defensive patterns

Strategy: validation

Validate before calling

const methods = initialization.authMethods?.map(m => m.id) ?? [];
if (!methods.includes(methodId)) {
  throw new Error(`Auth method ${methodId} not advertised; available: ${methods.join(', ') || 'none'}`);
}

Type guard

function isAdvertisedAuthMethod(initialization: ACPInitializeResult, methodId: string): boolean {
  return initialization.authMethods?.some(m => m.id === methodId) ?? false;
}

Try / catch

try {
  await bridge.authenticate({ methodId });
} catch (error) {
  if (error instanceof Error && error.message.includes('is not advertised')) {
    const advertised = error.message.match(/Advertised methods: (.*)\.$/)?.[1];
    console.error(`Pick one of: ${advertised}`);
  }
  throw error;
}

Prevention

Always derive the auth method id from initialization.authMethods rather than hardcoding it.
Pin agent versions so advertised capabilities do not drift.
Log advertised auth methods at startup for easier debugging.

When it happens

Trigger: Calling authenticate (via the ACP bridge) with a methodId that is not present in initialization.authMethods, e.g. a hardcoded id like 'oauth' when the agent only advertises other ids; also occurs when authMethods is missing/empty, in which case the advertised list shows 'none'.

Common situations: Configuring a harness with an auth method copied from a different agent version; an agent upgraded/downgraded so its advertised auth methods changed; a typo in the method id; agent fails to advertise any auth methods.

Understand the failure class

Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

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