apache/beam · error · RuntimeException

Unable to instantiate test options from system property %s:%

Error message

Unable to instantiate test options from system property %s:%s

What it means

TestPipeline.runWithAdditionalOptionArgs rebuilds pipeline options from the system property beamTestPipelineOptions (a JSON array of option strings). If deserializing/instantiating those options throws IOException, it is wrapped in a RuntimeException with this message identifying the offending property value.

Source

Thrown at sdks/java/core/src/main/java/org/apache/beam/sdk/testing/TestPipeline.java:417

      args.addAll(additionalArgs);
      String[] newArgs = Iterables.toArray(args, String.class);
      PipelineOptions newOptions =
          PipelineOptionsFactory.fromArgs(newArgs).as(TestPipelineOptions.class);

      // If no options were specified, set some reasonable defaults
      if (beamTestPipelineOptions.isEmpty()) {
        // If there are no provided options, check to see if a dummy runner should be used.
        String useDefaultDummy = System.getProperty(PROPERTY_USE_DEFAULT_DUMMY_RUNNER);
        if (!Strings.isNullOrEmpty(useDefaultDummy) && Boolean.valueOf(useDefaultDummy)) {
          newOptions.setRunner(CrashingRunner.class);
        }
      }
      newOptions.setStableUniqueNames(CheckEnabled.ERROR);

      FileSystems.registerFileSystemsOnce(options);
      return run(newOptions);
    } catch (IOException e) {
      throw new RuntimeException(
          "Unable to instantiate test options from system property "
              + PROPERTY_BEAM_TEST_PIPELINE_OPTIONS
              + ":"
              + System.getProperty(PROPERTY_BEAM_TEST_PIPELINE_OPTIONS),
          e);
    }
  }

  /** Like {@link #run} but with the given potentially modified options. */
  @Override
  public PipelineResult run(PipelineOptions options) {
    checkState(
        enforcement.isPresent(),
        "Is your TestPipeline declaration missing a @Rule annotation? Usage: "
            + "@Rule public final transient TestPipeline pipeline = TestPipeline.create();");

    final PipelineResult pipelineResult;
    try {

View on GitHub (pinned to 12126d8942)

Solutions

1. Print and validate the property value; ensure it is valid JSON, e.g. ["--runner=DirectRunner"].
2. Confirm every option name matches the current PipelineOptions class (check for renames in your Beam version).
3. Ensure the runner/options classes are on the test classpath.
4. Set the property in the build config with correct escaping (single quotes around the JSON in Maven surefire argLine).

Example fix

// before (Maven argLine)
-DbeamTestPipelineOptions=[--runner=DirectRunner]
// after
-DbeamTestPipelineOptions=[\"--runner=DirectRunner\"]

String opts = System.getProperty("beamTestPipelineOptions"); if (opts == null || !opts.trim().startsWith("[")) { throw new IllegalStateException("beamTestPipelineOptions must be a JSON array of strings"); }

try { pipeline.run(); } catch (RuntimeException e) { if (e.getMessage().startsWith("Unable to instantiate test options")) { /* fix the JSON in the system property */ } }

When it happens

Trigger: The system property PROPERTY_BEAM_TEST_PIPELINE_OPTIONS contains JSON that cannot be parsed into the configured options class (malformed JSON, unknown option fields, wrong types, or missing options class on the classpath).

Common situations: Setting -DbeamTestPipelineOptions with quotes escaped incorrectly in build tools (Maven/Gradle); options JSON referencing runner classes not on the test classpath; option renames after upgrading Beam.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• No filesystem found for scheme
• Exploded field %s must be an iterable type, got %s.
• boolean cross product parameter required to explode more tha
• ${config}
• Unknown log level ${level}. Valid log levels are ${validLeve

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