apache/beam · error · RuntimeException

Problems while trying to instantiate a dynamic web id token…

Error message

Problems while trying to instantiate a dynamic web id token provider class.

What it means

WebIdTokenProvider.create throws a RuntimeException wrapping ClassNotFoundException when the fully-qualified class name given for a dynamic OIDC web identity token provider cannot be loaded/instantiated via InstanceBuilder. It allows AWS2 IO users to plug in custom token providers by class name.

Solutions

1. Verify the FQCN spelling and that the class implements WebIdTokenProvider
2. Ensure the provider class is included in the pipeline jar/worker classpath
3. Check shading/relocation rules didn't rename the class in the fat jar
4. Give the provider a public no-arg constructor

Example fix

// before
WebIdTokenProvider.create("com.example.MyProvider"); // class not in jar
// after: bundle the class and use the exact FQCN
WebIdTokenProvider.create("com.example.providers.MyWebIdTokenProvider");

try {
  Class<?> c = Class.forName(providerFQCN);
  if (!WebIdTokenProvider.class.isAssignableFrom(c)) {
    throw new IllegalArgumentException(providerFQCN + " is not a WebIdTokenProvider");
  }
} catch (ClassNotFoundException e) {
  throw new IllegalArgumentException("provider not on classpath", e);
}

try {
  WebIdTokenProvider p = WebIdTokenProvider.create(fqcn);
} catch (RuntimeException e) {
  logger.error("check provider FQCN and worker jar contents", e);
  throw e;
}

When it happens

Trigger: Calling WebIdTokenProvider.create(providerFQCN) with a class name that is misspelled, not on the classpath, or not a subclass of WebIdTokenProvider.

Common situations: Typo or wrong package in the provider FQCN; custom provider class not bundled in the worker's fat jar; shaded/relocated class names after building a pipeline jar; class present but lacks a no-arg constructor.

Related errors

• Could not find class
• Could not find class:
• Could not find class
• Could not instantiate class
• Failed to locate DefaultGetSize.validateSize()

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

Appendix: source

Thrown at sdks/java/io/amazon-web-services2/src/main/java/org/apache/beam/sdk/io/aws2/auth/WebIdTokenProvider.java:39

/**
 * Defines the behavior for a OIDC web identity token provider. Instances of this interface will be
 * used by an AWS credentials provider which will send the OIDC Token retrieved to dynamically
 * refresh federated authorized credentials.
 */
public interface WebIdTokenProvider {
  /**
   * Factory method for OIDC web identity token provider implementations.
   *
   * @param providerFQCN The fully qualified class name of an implementation of {@link
   *     WebIdTokenProvider}.
   * @return An instance of {@link WebIdTokenProvider}.
   */
  static WebIdTokenProvider create(String providerFQCN) {
    try {
      return InstanceBuilder.ofType(WebIdTokenProvider.class).fromClassName(providerFQCN).build();
    } catch (ClassNotFoundException e) {
      throw new RuntimeException(
          "Problems while trying to instantiate a dynamic web id token provider class.", e);
    }
  }

  /**
   * Resolves the value for a OIDC web identity token.
   *
   * @param audience The audience for the token.
   * @return The encoded value for the OIDC web identity token.
   */
  String resolveTokenValue(String audience);
}

View on GitHub (pinned to 12126d8942)