mongodb/node-mongodb-native · critical · 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 OIDC machine workflow (gcp_machine_workflow.ts:26) when the TOKEN_RESOURCE mechanism property is missing. The driver needs TOKEN_RESOURCE as the audience query parameter for the GCP metadata endpoint (http://metadata/computeMetadata/v1/instance/service-accounts/default/identity) that mints OIDC tokens. Without it the driver cannot request a token scoped to your MongoDB cluster. It is raised as a MongoGCPError after the tokenAudience param is found falsy inside the gcpCallback.

Solutions

Add TOKEN_RESOURCE to authMechanismProperties: ...&authMechanismProperties=ENVIRONMENT:gcp,TOKEN_RESOURCE:<your-atlas-audience>
Confirm the TOKEN_RESOURCE value exactly equals the audience configured on your Atlas OIDC workload identity provider
Check the connection string is not URL-encoding the colon between ENVIRONMENT/TOKEN_RESOURCE keys and values
Verify mechanismProperties.TOKEN_RESOURCE reaches credentials by logging it before connect

Example fix

// before
const uri = 'mongodb://host/?authMechanism=MONGODB-OIDC&authMechanismProperties=ENVIRONMENT:gcp';

// after
const uri =
  'mongodb://host/?authMechanism=MONGODB-OIDC&authMechanismProperties=ENVIRONMENT:gcp,TOKEN_RESOURCE:https://cluster.example.mongodb.net';

Defensive patterns

Strategy: validation

Validate before calling

const mp = clientOptions.auth?.mechanismProperties ?? {};
if (mp.ENVIRONMENT === 'gcp' && !mp.TOKEN_RESOURCE) {
  throw new Error('TOKEN_RESOURCE is required for OIDC ENVIRONMENT=gcp');
}
// or, from a connection string, parse and assert before constructing MongoClient.

Type guard

function hasGcpTokenResource(mp: Record<string, unknown>): mp is { TOKEN_RESOURCE: string } {
  return typeof mp.TOKEN_RESOURCE === 'string' && mp.TOKEN_RESOURCE.length > 0;
}

Try / catch

try {
  await client.connect();
} catch (err) {
  if (err instanceof MongoGCPError && /TOKEN_RESOURCE/.test(err.message)) {
    // fix the connection string / mechanismProperties and retry
  } else throw err;
}

Prevention

Centralize OIDC connection-string building in one helper that always sets TOKEN_RESOURCE for gcp/azure
Assert mechanismProperties in a startup config validation step before connecting
Document the per-environment required properties next to your deployment config

When it happens

Trigger: Connecting with authMechanism='MONGODB-OIDC' and authMechanismProperties.ENVIRONMENT='gcp' while omitting the TOKEN_RESOURCE property; or passing an empty/falsy TOKEN_RESOURCE whose value does not propagate into params.tokenAudience (automated_callback_workflow.ts:72-73). Note MongoCredentials also validates this earlier at mongo_credentials.ts:211, so reaching this exact line usually means the credentials object was built bypassing that check.

Common situations: Copying an Azure OIDC connection string and changing ENVIRONMENT to gcp without adding the gcp TOKEN_RESOURCE. URL-encoding the mechanism properties so the colon-delimited TOKEN_RESOURCE is parsed as empty. Mixing up the property names (TOKEN_RESOURCE vs AUDIENCE).

Related errors

AI-assisted analysis of mongodb/node-mongodb-native@dce7939f86 (2026-08-11). Data as JSON: /api/errors/1348ba06f024c019. Report an issue: GitHub.

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