apache/beam · error · IllegalArgumentException

Unable to instantiate JMS ConnectionFactory of class

Error message

Unable to instantiate JMS ConnectionFactory of class ${className}. Must be a supported provider (ActiveMQ, Qpid, IBM MQ) or implement BeamGenericJmsConnectionFactory.

What it means

Thrown from ConnectionConfiguration.createConnectionFactory() when the class named by className loads but cannot be instantiated or fails to create the underlying ConnectionFactory. Beam requires either a known supported provider (ActiveMQ, Qpid, IBM MQ, via StandardJmsConnectionFactory) or a class implementing BeamGenericJmsConnectionFactory; anything else, or a constructor/session failure, results in this wrapped IllegalArgumentException.

Solutions

1. Use a class that implements BeamGenericJmsConnectionFactory (e.g. StandardJmsConnectionFactory / provider-specific Beam factories shipped with Beam)
2. If wrapping a vendor factory, implement BeamGenericJmsConnectionFactory with a public no-arg constructor and delegate createConnectionFactory(config) to the vendor factory
3. Check the cause exception for the real failure (constructor error, broker connectivity, auth) and fix that underlying issue
4. Align the JMS client library version with the one Beam was compiled against

Example fix

// before
ConnectionConfiguration.create(uri, user, pass, "org.apache.activemq.ActiveMQConnectionFactory")
// after
ConnectionConfiguration.create(uri, user, pass, "org.apache.beam.sdk.io.jms.StandardJmsConnectionFactory")

Class<?> c = Class.forName(className);
if (!BeamGenericJmsConnectionFactory.class.isAssignableFrom(c) && !isKnownProvider(c)) {
  throw new IllegalArgumentException(className + " must implement BeamGenericJmsConnectionFactory or be a supported provider");
}
try {
  c.getDeclaredConstructor().newInstance();
} catch (Exception e) {
  throw new IllegalStateException("Factory class lacks usable no-arg constructor: " + className);
}

try {
  pipeline.apply(JmsIO.read().withConnectionConfiguration(cfg));
} catch (IllegalArgumentException e) {
  if (e.getMessage() != null && e.getMessage().startsWith("Unable to instantiate JMS ConnectionFactory")) {
    // inspect e.getCause() for the real constructor/session failure
  } else throw e;
}

When it happens

Trigger: className resolves to a class that is not a supported provider and does not implement BeamGenericJmsConnectionFactory; or newInstance()/createConnectionFactory(this) throws (no-arg constructor missing, constructor throws, broker connection setup fails) inside the try block.

Common situations: Pointing className at the raw vendor ConnectionFactory (e.g. org.apache.activemq.ActiveMQConnectionFactory directly) instead of the Beam standard factory; client library version mismatch causing factory init to fail; broker rejecting the connection during factory creation.

Related errors

• Attempting to add message
• bad decode
• bad encode
• Can not call prepareRun
• Cannot determine context class

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

Appendix: source

Thrown at sdks/java/io/jms/src/main/java/org/apache/beam/sdk/io/jms/ConnectionConfiguration.java:136

          e);
    }
    if (BeamGenericJmsConnectionFactory.class.isAssignableFrom(clazz)) {
      factoryClass = (Class<? extends BeamGenericJmsConnectionFactory>) clazz;
    } else if (className.contains("org.apache.activemq.ActiveMQConnectionFactory")
        || className.contains("org.apache.qpid.jms")) {
      // Connectors supported by StandardJmsConnectionFactory
      factoryClass = StandardJmsConnectionFactory.class;
    } else if (className.contains("com.ibm.mq")) {
      factoryClass = IbmMqJmsConnectionFactory.class;
    } else {
      // Attempt to use StandardJmsConnectionFactory.class;
      factoryClass = StandardJmsConnectionFactory.class;
    }
    try {
      BeamGenericJmsConnectionFactory factory = factoryClass.getDeclaredConstructor().newInstance();
      return factory.createConnectionFactory(this);
    } catch (Exception e) {
      throw new IllegalArgumentException(
          "Unable to instantiate JMS ConnectionFactory of class "
              + className
              + ". Must be a supported provider (ActiveMQ, Qpid, IBM MQ) or implement BeamGenericJmsConnectionFactory.",
          e);
    }
  }

  /**
   * A {@link BeamGenericJmsConnectionFactory} implementation for standard JMS connection factories.
   */
  public static class StandardJmsConnectionFactory implements BeamGenericJmsConnectionFactory {

    @Override
    public ConnectionFactory createConnectionFactory(ConnectionConfiguration config)
        throws Exception {
      String className = config.getConnectionFactoryClassName();
      if (className == null || className.isEmpty()) {
        className = "org.apache.activemq.ActiveMQConnectionFactory";

View on GitHub (pinned to 12126d8942)