{"record":{"id":"7add5faa1778e61e","repo":"apache/beam","slug":"connectionfactory-classname-does-not-exist-if-using","errorCode":null,"errorMessage":"ConnectionFactory ${className} does not exist. If using expansion service, attach the connection factory jar as part of its invocation classpath.","messagePattern":"ConnectionFactory (.+?) does not exist\\. If using expansion service, attach the connection factory jar as part of its invocation classpath\\.","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"sdks/java/io/jms/src/main/java/org/apache/beam/sdk/io/jms/ConnectionConfiguration.java","lineNumber":114,"sourceCode":"    public abstract Builder setUsername(@Nullable String username);\n\n    public abstract Builder setPassword(@Nullable String password);\n\n    public abstract ConnectionConfiguration build();\n  }\n\n  public ConnectionFactory createConnectionFactory() {\n    String className = getConnectionFactoryClassName();\n    // Default to ActiveMQ\n    if (className == null || className.isEmpty()) {\n      className = \"org.apache.activemq.ActiveMQConnectionFactory\";\n    }\n    Class<?> clazz;\n    Class<? extends BeamGenericJmsConnectionFactory> factoryClass;\n    try {\n      clazz = Class.forName(className);\n    } catch (ClassNotFoundException e) {\n      throw new IllegalArgumentException(\n          String.format(\n              \"ConnectionFactory %s does not exist. If using expansion service, attach the connection factory jar as part of its invocation classpath.\",\n              className),\n          e);\n    }\n    if (BeamGenericJmsConnectionFactory.class.isAssignableFrom(clazz)) {\n      factoryClass = (Class<? extends BeamGenericJmsConnectionFactory>) clazz;\n    } else if (className.contains(\"org.apache.activemq.ActiveMQConnectionFactory\")\n        || className.contains(\"org.apache.qpid.jms\")) {\n      // Connectors supported by StandardJmsConnectionFactory\n      factoryClass = StandardJmsConnectionFactory.class;\n    } else if (className.contains(\"com.ibm.mq\")) {\n      factoryClass = IbmMqJmsConnectionFactory.class;\n    } else {\n      // Attempt to use StandardJmsConnectionFactory.class;\n      factoryClass = StandardJmsConnectionFactory.class;\n    }\n    try {","sourceCodeStart":96,"sourceCodeEnd":132,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/io/jms/src/main/java/org/apache/beam/sdk/io/jms/ConnectionConfiguration.java#L96-L132","documentation":"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.","triggerScenarios":"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.","commonSituations":"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).","solutions":["Add the broker's JMS client jar to the pipeline/expansion service classpath (e.g. activemq-client, qpid-jms-client, com.ibm.mq.allclient)","Verify the className string is the correct fully-qualified class for the installed client version (check its javadoc/jar contents)","If using an expansion service, pass the connection factory jar in its invocation classpath (extra classpath/setup files)","Confirm the dependency scope is compile/runtime, not provided, so it lands in the submitted jar"],"exampleFix":"// before\nConnectionConfiguration.create(\"tcp://broker:61616\", \"user\", \"pass\", \"com.example.MissingFactory\")\n// after\nConnectionConfiguration.create(\"tcp://broker:61616\", \"user\", \"pass\", \"org.apache.activemq.ActiveMQConnectionFactory\")\n// and include: implementation(\"org.apache.activemq:activemq-client:x.y.z\")","handlingStrategy":"validation","validationCode":"try {\n  Class.forName(className);\n} catch (ClassNotFoundException e) {\n  throw new IllegalStateException(\"JMS ConnectionFactory class missing from runtime classpath: \" + className\n      + \". Add the broker client jar to the pipeline/expansion service classpath.\");\n}","typeGuard":null,"tryCatchPattern":"try {\n  PCollection<?> out = pipeline.apply(JmsIO.read().withConnectionConfiguration(cfg));\n} catch (IllegalArgumentException e) {\n  if (e.getMessage() != null && e.getMessage().startsWith(\"ConnectionFactory \")) {\n    // attach vendor JMS client jar / fix className, then resubmit\n  } else throw e;\n}","preventionTips":["Bundle the broker client jar (activemq-client, qpid-jms-client, com.ibm.mq.allclient) as a compile/runtime dependency","For expansion services, attach the connection factory jar in the invocation classpath","Verify className via Class.forName in a unit test before submitting the pipeline"],"tags":["jms","classpath","classnotfound","beam"],"backgroundTag":"class-not-found","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-15T02:17:10.978Z"}