apache/beam · error · IllegalArgumentException

No Runner was specified and the DirectRunner was not found o

Error message

No Runner was specified and the DirectRunner was not found on the classpath.%nSpecify a runner by either:%n    Explicitly specifying a runner by providing the 'runner' property%n    Adding the DirectRunner to the classpath%n    Calling 'PipelineOptions.setRunner(PipelineRunner)' directly

What it means

PipelineOptions.create() resolves the runner: if no --runner property was given, it tries to load the DirectRunner class reflectively. When neither a runner is specified nor DirectRunner is on the classpath, it throws IllegalArgumentException listing the ways to specify a runner.

Source

Thrown at sdks/java/core/src/main/java/org/apache/beam/sdk/options/PipelineOptions.java:316

   *
   * <p>As the {@code DirectRunner} is in an independent module, it cannot be directly referenced as
   * the {@link Default}. However, it should still be used if available, and a user is required to
   * explicitly set the {@code --runner} property if they wish to use an alternative runner.
   */
  class DirectRunner implements DefaultValueFactory<Class<? extends PipelineRunner<?>>> {
    @Override
    public Class<? extends PipelineRunner<?>> create(PipelineOptions options) {
      try {
        @SuppressWarnings({"unchecked", "rawtypes"})
        Class<? extends PipelineRunner<?>> direct =
            (Class<? extends PipelineRunner<?>>)
                Class.forName(
                    "org.apache.beam.runners.direct.DirectRunner",
                    true,
                    ReflectHelpers.findClassLoader());
        return direct;
      } catch (ClassNotFoundException e) {
        throw new IllegalArgumentException(
            String.format(
                "No Runner was specified and the DirectRunner was not found on the classpath.%n"
                    + "Specify a runner by either:%n"
                    + "    Explicitly specifying a runner by providing the 'runner' property%n"
                    + "    Adding the DirectRunner to the classpath%n"
                    + "    Calling 'PipelineOptions.setRunner(PipelineRunner)' directly"));
      }
    }
  }

  /**
   * Returns a normalized job name constructed from {@link ApplicationNameOptions#getAppName()}, the
   * local system user name (if available), the current time, and a random integer.
   *
   * <p>The normalization makes sure that the name matches the pattern of
   * [a-z]([-a-z0-9]*[a-z0-9])?.
   */
  class JobNameFactory implements DefaultValueFactory<String> {

View on GitHub (pinned to 12126d8942)

Solutions

Set the runner: --runner=<YourRunner> via options, argv, or PipelineOptionsFactory.fromArgs.
Call PipelineOptions.setRunner(YourRunner.class) programmatically before building the Pipeline.
Add the desired runner artifact (e.g. beam-runners-direct-java, beam-runners-dataflow-java) to the classpath.
In production, always configure --runner explicitly rather than relying on the DirectRunner default.

Example fix

// before
PipelineOptions options = PipelineOptionsFactory.create();
// after
PipelineOptions options = PipelineOptionsFactory.fromArgs(new String[]{"--runner=FlinkRunner"}).create();

Defensive patterns

Strategy: validation

Validate before calling

if (options.getRunner() == null && !hasClass("org.apache.beam.runners.direct.DirectRunner")) { options.setRunner(ProductionRunner.class); }

Try / catch

try { pipeline = Pipeline.create(options); } catch (IllegalArgumentException e) { LOG.error("runner misconfigured: " + e.getMessage()); throw e; }

Prevention

Always pass --runner explicitly in non-interactive environments
Ship a runner artifact with your application dependencies
Fail fast with a startup check for the configured runner class

When it happens

Trigger: Calling PipelineOptions.create() (or Pipeline.create()) without a --runner option while beam-runners-direct-java is absent from the classpath — common in slim production images or when depending only on sdks-core.

Common situations: Production deployments that removed the DirectRunner but forgot to set --runner, libraries embedding Beam without a runner dependency, and tests running outside the default Beam classpath.

Related errors

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