mongodb/node-mongodb-native · error · MongoInvalidArgumentError

Could not load workflow for environment ${authMechanismPrope

Error message

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

What it means

Thrown by getWorkflow() when MONGODB-OIDC is used without a callback (OIDC_HUMAN_CALLBACK/OIDC_CALLBACK) and the configured ENVIRONMENT does not map to a known workflow in OIDC_WORKFLOWS. Known environments are aws, gcp, azure, and test. An unrecognized ENVIRONMENT string means the driver cannot pick a token-acquisition strategy. MongoInvalidArgumentError.

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 3366c21a63)

Solutions

Use one of the supported ENVIRONMENT values: aws, gcp, azure, or test.
If you have a custom token source, provide OIDC_HUMAN_CALLBACK or OIDC_CALLBACK instead of ENVIRONMENT.
Verify the value is lowercase and exactly matches a supported environment.

Example fix

// before
const uri = 'mongodb://u@h/?authMechanism=MONGODB-OIDC&authMechanismProperties=ENVIRONMENT:awss';

// after
const uri = 'mongodb://u@h/?authMechanism=MONGODB-OIDC&authMechanismProperties=ENVIRONMENT:aws';

Defensive patterns

Strategy: validation

Validate before calling

const OIDC_ENVS = new Set(['aws','gcp','azure','test']);
if (env && !OIDC_ENVS.has(env)) throw new Error('Unknown OIDC ENVIRONMENT');

Type guard

function isKnownOidcEnv(v): v is 'aws'|'gcp'|'azure'|'test' {
  return ['aws','gcp','azure','test'].includes(v);
}

Prevention

Use lowercase ENVIRONMENT values
Provide a callback for custom OIDC flows
Validate ENVIRONMENT at config load time

When it happens

Trigger: Setting authMechanismProperties=ENVIRONMENT:<value> to something other than aws/gcp/azure/test while using MONGODB-OIDC without a callback. Typos like 'AWS' (case) or 'awss'.

Common situations: Migrating between cloud providers; typos in ENVIRONMENT; specifying ENVIRONMENT when you actually intend callback-based OIDC.

Related errors

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