{"record":{"id":"1cdafd4f22c13115","repo":"apache/beam","slug":"unknown-runner-specified-s-supported-pipeline-runners-s","errorCode":null,"errorMessage":"Unknown 'runner' specified '%s', supported pipeline runners %s","messagePattern":"Unknown 'runner' specified '(.+?)', supported pipeline runners (.+?)","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"sdks/java/core/src/main/java/org/apache/beam/sdk/options/PipelineOptionsFactory.java","lineNumber":1936,"sourceCode":"          if (pipelineRunners.containsKey(runner.toLowerCase())) {\n            convertedOptions.put(\"runner\", pipelineRunners.get(runner.toLowerCase(ROOT)));\n          } else {\n            try {\n              Class<?> runnerClass = Class.forName(runner, true, ReflectHelpers.findClassLoader());\n              if (!PipelineRunner.class.isAssignableFrom(runnerClass)) {\n                throw new IllegalArgumentException(\n                    String.format(\n                        \"Class '%s' does not implement PipelineRunner. \"\n                            + \"Supported pipeline runners %s\",\n                        runner, cache.getSupportedRunners()));\n              }\n              convertedOptions.put(\"runner\", runnerClass);\n            } catch (ClassNotFoundException e) {\n              String msg =\n                  String.format(\n                      \"Unknown 'runner' specified '%s', supported pipeline runners %s\",\n                      runner, cache.getSupportedRunners());\n              throw new IllegalArgumentException(msg, e);\n            }\n          }\n        } else if (isCollectionOrArrayOfAllowedTypes(returnType, type)) {\n          // Split any strings with \",\"\n          List<String> values =\n              entry.getValue().stream()\n                  .flatMap(input -> Arrays.stream(input.split(\",\")))\n                  .collect(Collectors.toList());\n\n          if (values.contains(\"\")) {\n            checkEmptyStringAllowed(returnType, type, method.getGenericReturnType().toString());\n          }\n          convertedOptions.put(entry.getKey(), MAPPER.convertValue(values, type));\n        } else if (isSimpleType(returnType, type)) {\n          String value = Iterables.getOnlyElement(entry.getValue());\n          if (value.isEmpty()) {\n            checkEmptyStringAllowed(returnType, type, method.getGenericReturnType().toString());\n          }","sourceCodeStart":1918,"sourceCodeEnd":1954,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/core/src/main/java/org/apache/beam/sdk/options/PipelineOptionsFactory.java#L1918-L1954","documentation":"The 'runner' option value could not be loaded: Class.forName threw ClassNotFoundException, so Beam wraps it in an IllegalArgumentException listing the supported registered runners. This means the runner is neither a registered short name nor a class present on the classpath.","triggerScenarios":"Passing --runner=SomeRunner where SomeRunner is not in the supported-runners registry and its fully-qualified class name is absent from the classpath.","commonSituations":"Missing the runner-specific dependency (e.g., beam-runners-direct-java not on classpath); typo in the runner class name; using a runner name from a different Beam version.","solutions":["Add the runner's dependency artifact to the classpath (e.g., beam-runners-direct-java, beam-runners-google-cloud-dataflow-java)","Use a registered short runner name like DirectRunner or DataflowRunner","Check the supported runners listed in the error and pick one that your dependencies provide"],"exampleFix":"// before\n--runner=FlinkRunner   // flink runner jar not on classpath\n// after\ndependencies { runtimeOnly \"org.apache.beam:beam-runners-flink-1.17:2.x.x\" }\n// or use: --runner=DirectRunner","handlingStrategy":"fallback","validationCode":"try { Class.forName(runnerClass, true, cl); } catch (ClassNotFoundException e) { /* use default runner */ }","typeGuard":null,"tryCatchPattern":"try { PipelineOptionsFactory.fromArgs(\"--runner=\" + runner).create(); } catch (IllegalArgumentException e) { options.setRunner(DirectRunner.class); }","preventionTips":["Ensure the runner dependency artifact is on the runtime classpath","Prefer short registered runner names over FQCNs","Verify runner availability at startup, not at pipeline submission"],"tags":["java","apache-beam","runner","classpath","missing-dependency"],"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-14T16:17:12.679Z"}