apache/beam · error · IllegalStateException

is not

Error message

${className} is not ${superType}

What it means

InstanceUtils.forName loads a class by name from the thread context classloader and verifies it is assignable to the requested superType; if it loads but is not a subtype it throws IllegalStateException with '<className> is not <superType>'. A ClassNotFoundException is also wrapped into IllegalStateException.

Solutions

1. Fix the configured class name so it points to a subclass of the expected superType
2. Check the FQCN for typos or an outdated class after a refactor
3. Verify the class's hierarchy (extends/implements) matches what the API expects

Example fix

// before
options.setCombiner("com.example.MyHelper"); // not a WindowedCombiner
// after
options.setCombiner("com.example.MyWindowedCombiner"); // implements WindowedCombiner

Class<?> c = Class.forName(className); if (!superType.isAssignableFrom(c)) throw new IllegalArgumentException(className + " must be a " + superType.getSimpleName());

static <T> boolean isSubtype(String className, Class<T> superType) { try { return superType.isAssignableFrom(Class.forName(className)); } catch (ClassNotFoundException e) { return false; } }

try { cls = InstanceUtils.forName(name, Super.class); } catch (IllegalStateException e) { /* fix configured class name */ }

When it happens

Trigger: Calling InstanceUtils.forName("com.example.Foo", SomeSuper.class) where the class exists but does not extend/implement SomeSuper.

Common situations: Misconfigured provider class names in pipeline options (e.g. specifying a combiner/reducer class of the wrong type); copy-pasted FQCNs pointing at unrelated classes.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

• element type is , want
• Incompatible func type: got func
• Invalid output type in method
• invalid types for map update
• Mismatched output type in method

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

Appendix: source

Thrown at sdks/java/extensions/euphoria/src/main/java/org/apache/beam/sdk/extensions/euphoria/core/util/InstanceUtils.java:57

      constr.setAccessible(true);
      return constr.newInstance();
    } catch (Exception e) {
      throw new IllegalStateException(e);
    }
  }

  public static <T> T create(String className, Class<T> superType) {
    return create(forName(className, superType));
  }

  @SuppressWarnings("unchecked")
  public static <T> Class<? extends T> forName(String className, Class<T> superType) {
    try {
      Class<?> cls = Thread.currentThread().getContextClassLoader().loadClass(className);
      if (superType.isAssignableFrom(cls)) {
        return (Class<? extends T>) cls;
      } else {
        throw new IllegalStateException(className + " is not " + superType);
      }
    } catch (ClassNotFoundException e) {
      throw new IllegalStateException(e);
    }
  }
}

View on GitHub (pinned to 12126d8942)