apache/beam · error · IllegalArgumentException

ConnectionFactory ${className} does not exist. If using expa

Error message

ConnectionFactory ${className} does not exist. If using expansion service, attach the connection factory jar as part of its invocation classpath.

What it means

Thrown from ConnectionConfiguration.createConnectionFactory() in JmsIO when Class.forName cannot locate the configured ConnectionFactory class name. Beam loads the JMS ConnectionFactory reflectively at pipeline runtime, so the class must be present on the runtime classpath; if it is missing the configuration is invalid.

Source

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

    public abstract Builder setUsername(@Nullable String username);

    public abstract Builder setPassword(@Nullable String password);

    public abstract ConnectionConfiguration build();
  }

  public ConnectionFactory createConnectionFactory() {
    String className = getConnectionFactoryClassName();
    // Default to ActiveMQ
    if (className == null || className.isEmpty()) {
      className = "org.apache.activemq.ActiveMQConnectionFactory";
    }
    Class<?> clazz;
    Class<? extends BeamGenericJmsConnectionFactory> factoryClass;
    try {
      clazz = Class.forName(className);
    } catch (ClassNotFoundException e) {
      throw new IllegalArgumentException(
          String.format(
              "ConnectionFactory %s does not exist. If using expansion service, attach the connection factory jar as part of its invocation classpath.",
              className),
          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 {

View on GitHub (pinned to 12126d8942)

Solutions

  1. Add the broker's JMS client jar to the pipeline/expansion service classpath (e.g. activemq-client, qpid-jms-client, com.ibm.mq.allclient)
  2. Verify the className string is the correct fully-qualified class for the installed client version (check its javadoc/jar contents)
  3. If using an expansion service, pass the connection factory jar in its invocation classpath (extra classpath/setup files)
  4. Confirm the dependency scope is compile/runtime, not provided, so it lands in the submitted jar

Example fix

// before
ConnectionConfiguration.create("tcp://broker:61616", "user", "pass", "com.example.MissingFactory")
// after
ConnectionConfiguration.create("tcp://broker:61616", "user", "pass", "org.apache.activemq.ActiveMQConnectionFactory")
// and include: implementation("org.apache.activemq:activemq-client:x.y.z")
Defensive patterns

Strategy: validation

Validate before calling

try {
  Class.forName(className);
} catch (ClassNotFoundException e) {
  throw new IllegalStateException("JMS ConnectionFactory class missing from runtime classpath: " + className
      + ". Add the broker client jar to the pipeline/expansion service classpath.");
}

Try / catch

try {
  PCollection<?> out = pipeline.apply(JmsIO.read().withConnectionConfiguration(cfg));
} catch (IllegalArgumentException e) {
  if (e.getMessage() != null && e.getMessage().startsWith("ConnectionFactory ")) {
    // attach vendor JMS client jar / fix className, then resubmit
  } else throw e;
}

Prevention

When it happens

Trigger: Calling JmsIO.read()/write() (or cf()) with a ConnectionConfiguration whose className is not on the runtime classpath — typically when the JMS broker client jar (ActiveMQ, Qpid, IBM MQ) is not bundled with the job or expansion service.

Common situations: Running via a Beam expansion service without attaching the vendor JMS client jar; fat-jar/shadow-jar build missing the broker dependency (provided scope); typo in the fully-qualified class name after a vendor client version upgrade (e.g. ActiveMQ class renames).

Related errors

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