mongodb/node-mongodb-native · error · MongoGCPError

TOKEN_RESOURCE must be set in the auth mechanism properties

Error message

TOKEN_RESOURCE must be set in the auth mechanism properties when ENVIRONMENT is gcp.

What it means

Thrown by the GCP machine OIDC workflow when ENVIRONMENT is set to 'gcp' but TOKEN_RESOURCE is missing (src/cmap/auth/mongodb_oidc/gcp_machine_workflow.ts:25). TOKEN_RESOURCE becomes the 'audience' query parameter passed to the GCP metadata service token endpoint and is required. Surfaced as a MongoGCPError.

Source

Thrown at src/cmap/auth/mongodb_oidc/gcp_machine_workflow.ts:26

/** GCP request headers. */
const GCP_HEADERS = Object.freeze({ 'Metadata-Flavor': 'Google' });

/** Error for when the token audience is missing in the environment. */
const TOKEN_RESOURCE_MISSING_ERROR =
  'TOKEN_RESOURCE must be set in the auth mechanism properties when ENVIRONMENT is gcp.';

/**
 * The callback function to be used in the automated callback workflow.
 * @param params - The OIDC callback parameters.
 * @returns The OIDC response.
 */
export const gcpCallback: OIDCCallbackFunction = async (
  params: OIDCCallbackParams
): Promise<OIDCResponse> => {
  const tokenAudience = params.tokenAudience;
  if (!tokenAudience) {
    throw new MongoGCPError(TOKEN_RESOURCE_MISSING_ERROR);
  }
  return await getGcpTokenData(tokenAudience);
};

/**
 * Hit the GCP endpoint to get the token data.
 */
async function getGcpTokenData(tokenAudience: string): Promise<OIDCResponse> {
  const url = new URL(GCP_BASE_URL);
  url.searchParams.append('audience', tokenAudience);
  const response = await get(url, {
    headers: GCP_HEADERS
  });
  if (response.status !== 200) {
    throw new MongoGCPError(
      `Status code ${response.status} returned from the GCP endpoint. Response body: ${response.body}`
    );
  }

View on GitHub (pinned to 3366c21a63)

Solutions

1. Add TOKEN_RESOURCE to authMechanismProperties, e.g. ENVIRONMENT:gcp,TOKEN_RESOURCE:<mongodb-cluster-audience>.
2. Confirm the TOKEN_RESOURCE matches the audience configured on the MongoDB server for OIDC.
3. Use exact property casing and comma-separate multiple properties in the connection string.

Example fix

// before
const c = new MongoClient('mongodb://host/?authMechanism=MONGODB-OIDC&authMechanismProperties=ENVIRONMENT:gcp');

// after
const c = new MongoClient(
  'mongodb://host/?authMechanism=MONGODB-OIDC&authMechanismProperties=ENVIRONMENT:gcp,TOKEN_RESOURCE:https://cluster.example.com'
);

function validateGcpOidcProps(props: Record<string, unknown>): void {
  if (props.ENVIRONMENT === 'gcp' && !props.TOKEN_RESOURCE) {
    throw new Error('TOKEN_RESOURCE is required when ENVIRONMENT=gcp');
  }
}
validateGcpOidcProps(parsedMechanismProperties);

function isGcpOidcConfig(props: unknown): props is { ENVIRONMENT: 'gcp'; TOKEN_RESOURCE: string } {
  return !!props && typeof props === 'object'
    && (props as any).ENVIRONMENT === 'gcp'
    && typeof (props as any).TOKEN_RESOURCE === 'string';
}

When it happens

Trigger: Connecting with MONGODB-OIDC and authMechanismProperties=ENVIRONMENT:gcp but omitting TOKEN_RESOURCE. The gcpCallback checks params.tokenAudience and throws before contacting the GCP metadata endpoint.

Common situations: Missing or misspelled TOKEN_RESOURCE in the connection string, copy-paste from GCP docs that used a different property name, or assuming the GCP metadata service does not need an audience.

Related errors

• TOKEN_RESOURCE must be set in the auth mechanism properties
• TOKEN_RESOURCE must be set in the auth mechanism properties
• User provided OIDC callbacks must return a valid object with
• No workflow provided to the OIDC auth provider.
• AuthContext must provide credentials.

AI-assisted analysis of mongodb/node-mongodb-native@3366c21a63 (2026-08-04). Data as JSON: /data/errors/1348ba06f024c019.json. Report an issue: GitHub.