apache/beam · error · java.lang.IllegalArgumentException

username is required for password and private key…

Error message

username is required for password and private key authentication.

What it means

validateAuthentication also enforces that when password or privateKey authentication is used, a username must be supplied. Missing username throws IllegalArgumentException('username is required for password and private key authentication.').

Solutions

Add the Snowflake username: setUsername("MY_USER").
Ensure the username value resolves to a non-empty string (env var/secret injection).
Switch to oauthToken authentication if no username should be embedded.
Validate the config before submit so the missing field surfaces early.

Example fix

// before
builder.setPrivateKey(pem); // no username
// after
builder.setPrivateKey(pem).setUsername("SNOWFLAKE_USER");

Defensive patterns

Strategy: validation

Validate before calling

if ((isNotEmpty(password) || isNotEmpty(privateKey)) && !isNotEmpty(username)) {
  throw new IllegalArgumentException("username is required when using password or privateKey auth");
}

Prevention

Pair username with every password/privateKey configuration.
Verify injected username env/secrets resolve before submit.
Use oauthToken if username capture is problematic.

When it happens

Trigger: Setting password or privateKey but leaving username null/empty in SnowflakeSchemaTransformUtils.validateAuthentication.

Common situations: OAuth-only flows reused with a password added but no username; Snowflake usernames with special casing omitted; config templates that assume username comes from the environment.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

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

Related errors

AI-assisted analysis of apache/beam@12126d8942 (2026-09-13). Data as JSON: /api/errors/17284b3966a68235. Report an issue: GitHub.

Appendix: source

Thrown at sdks/java/io/snowflake/src/main/java/org/apache/beam/sdk/io/snowflake/SnowflakeSchemaTransformUtils.java:111

      authenticationMethods++;
    }

    if (isNotEmpty(oauthToken)) {
      authenticationMethods++;
    }

    if (isNotEmpty(privateKey)) {
      authenticationMethods++;
    }

    if (authenticationMethods != 1) {
      throw new IllegalArgumentException(
          "Exactly one authentication method must be configured: "
              + "password, oauthToken, or privateKey.");
    }

    if ((isNotEmpty(password) || isNotEmpty(privateKey)) && !isNotEmpty(username)) {
      throw new IllegalArgumentException(
          "username is required for password and private key authentication.");
    }

    if (isNotEmpty(privateKeyPassphrase) && !isNotEmpty(privateKey)) {
      throw new IllegalArgumentException("privateKeyPassphrase requires privateKey.");
    }
  }

  @EnsuresNonNullIf(expression = "#1", result = true)
  public static boolean isNotEmpty(@Nullable String value) {
    return value != null && !value.isEmpty();
  }

  public static StreamingLogLevel parseStreamingLogLevel(String value) {
    try {
      return StreamingLogLevel.valueOf(value);
    } catch (IllegalArgumentException e) {
      throw new IllegalArgumentException(

View on GitHub (pinned to 12126d8942)