mongodb/node-mongodb-native · error · MongoInvalidArgumentError

Could not load workflow for environment

Error message

Could not load workflow for environment ${authMechanismProperties.ENVIRONMENT}

What it means

Thrown during MONGODB-OIDC setup when no callback is supplied and the ENVIRONMENT value is not one of the built-in workflows ('test', 'azure', 'gcp', 'k8s'). The driver needs either an OIDC_CALLBACK/OIDC_HUMAN_CALLBACK or a recognized cloud ENVIRONMENT to construct a token-fetching workflow.

Solutions

1. Use one of the built-in environments: 'test', 'azure', 'gcp', 'k8s'.
2. If you need a custom or unsupported provider, supply OIDC_CALLBACK (machine) or OIDC_HUMAN_CALLBACK (interactive) via authMechanismProperties instead of ENVIRONMENT.
3. Upgrade the driver — newer versions may add built-in workflows for additional providers.

Example fix

// before
const client = new MongoClient(url, {
  authMechanismProperties: { ENVIRONMENT: 'aws' } // not supported
});

// after (custom provider via callback)
const client = new MongoClient(url, {
  authMechanismProperties: { OIDC_CALLBACK: async () => ({ accessToken: getToken() }) }
});

const OIDC_ENVS = new Set(['test', 'azure', 'gcp', 'k8s']);
const props = credentials.authMechanismProperties ?? {};
if (credentials.mechanism === 'MONGODB-OIDC' && props.ENVIRONMENT &&
    !OIDC_ENVS.has(props.ENVIRONMENT) &&
    !props.OIDC_CALLBACK && !props.OIDC_HUMAN_CALLBACK) {
  throw new Error(`Unknown OIDC ENVIRONMENT: ${props.ENVIRONMENT}`);
}

type OidcEnv = 'test' | 'azure' | 'gcp' | 'k8s';
const isOidcEnv = (v: unknown): v is OidcEnv =>
  typeof v === 'string' && ['test','azure','gcp','k8s'].includes(v);

When it happens

Trigger: Configuring MONGODB-OIDC with authMechanismProperties.ENVIRONMENT set to an unrecognized value (e.g. 'aws', 'azure-cloud', typo) while omitting both OIDC_CALLBACK and OIDC_HUMAN_CALLBACK.

Common situations: Misreading the OIDC spec and assuming AWS is supported via ENVIRONMENT; typos in environment names; using newer cloud providers the driver version doesn't yet ship a built-in workflow for.

Related errors

• Auth mechanism property ALLOWED_HOSTS must be an array of…
• AuthContext must provide credentials.
• authMechanism not supported
• Azure endpoint did not return a value with only…
• Currently only a ENVIRONMENT in

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

Appendix: source

Thrown at src/mongo_client_auth_providers.ts:81

    const provider = providerFunction(authMechanismProperties);
    this.existingProviders.set(name, provider);
    return provider;
  }
}

/**
 * Gets either a device workflow or callback workflow.
 */
function getWorkflow(authMechanismProperties: AuthMechanismProperties): Workflow {
  if (authMechanismProperties.OIDC_HUMAN_CALLBACK) {
    return new HumanCallbackWorkflow(new TokenCache(), authMechanismProperties.OIDC_HUMAN_CALLBACK);
  } else if (authMechanismProperties.OIDC_CALLBACK) {
    return new AutomatedCallbackWorkflow(new TokenCache(), authMechanismProperties.OIDC_CALLBACK);
  } else {
    const environment = authMechanismProperties.ENVIRONMENT;
    const workflow = OIDC_WORKFLOWS.get(environment)?.();
    if (!workflow) {
      throw new MongoInvalidArgumentError(
        `Could not load workflow for environment ${authMechanismProperties.ENVIRONMENT}`
      );
    }
    return workflow;
  }
}

View on GitHub (pinned to dce7939f86)