apache/beam · error · java.lang.IllegalArgumentException

privateKeyPassphrase requires privateKey.

Error message

privateKeyPassphrase requires privateKey.

What it means

SnowflakeSchemaTransformUtils.validateAuthentication enforces that a private key passphrase only makes sense alongside an actual private key. If privateKeyPassphrase is set (non-null and non-empty) but privateKey is missing, the config is considered invalid and an IllegalArgumentException is thrown during validation of the Snowflake transform configuration.

Solutions

1. Set privateKey (PEM content or key path depending on config) alongside privateKeyPassphrase.
2. Remove privateKeyPassphrase if you are not using private key authentication.
3. Validate config early with validateAuthentication before submitting the pipeline.

Example fix

// before
.withUsername("user")
.withPrivateKeyPassphrase("s3cret")
// after
.withUsername("user")
.withPrivateKey("-----BEGIN PRIVATE KEY-----\n...")
.withPrivateKeyPassphrase("s3cret")

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

When it happens

Trigger: Calling a Snowflake IO schema transform (read/write) configuration builder with privateKeyPassphrase set but privateKey null or empty, then invoking validateAuthentication.

Common situations: Copying config from a key-pair auth example but forgetting to supply the private key; loading the passphrase from a secret manager while the key path/env var failed to resolve; switching auth methods from key-pair to password and leaving the passphrase behind.

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.

Related errors

• Either table or query must be specified.
• Exactly one authentication method must be configured…
• Failed to setLoginTimeout
• flushRowLimit must be greater than 0.
• flushTimeLimitMillis must be greater than 0.

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

Appendix: source

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

    }

    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(
          "Unsupported debugMode '" + value + "'. Supported values are ERROR and INFO.", e);
    }
  }

  public static CreateDisposition parseCreateDisposition(String value) {

View on GitHub (pinned to 12126d8942)