{"record":{"id":"f5e96335d85efe65","repo":"apache/beam","slug":"unable-to-instantiate-test-options-from-system-property-s-s","errorCode":null,"errorMessage":"Unable to instantiate test options from system property %s:%s","messagePattern":"Unable to instantiate test options from system property (.+?):(.+?)","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"sdks/java/core/src/main/java/org/apache/beam/sdk/testing/TestPipeline.java","lineNumber":417,"sourceCode":"      args.addAll(additionalArgs);\n      String[] newArgs = Iterables.toArray(args, String.class);\n      PipelineOptions newOptions =\n          PipelineOptionsFactory.fromArgs(newArgs).as(TestPipelineOptions.class);\n\n      // If no options were specified, set some reasonable defaults\n      if (beamTestPipelineOptions.isEmpty()) {\n        // If there are no provided options, check to see if a dummy runner should be used.\n        String useDefaultDummy = System.getProperty(PROPERTY_USE_DEFAULT_DUMMY_RUNNER);\n        if (!Strings.isNullOrEmpty(useDefaultDummy) && Boolean.valueOf(useDefaultDummy)) {\n          newOptions.setRunner(CrashingRunner.class);\n        }\n      }\n      newOptions.setStableUniqueNames(CheckEnabled.ERROR);\n\n      FileSystems.registerFileSystemsOnce(options);\n      return run(newOptions);\n    } catch (IOException e) {\n      throw new RuntimeException(\n          \"Unable to instantiate test options from system property \"\n              + PROPERTY_BEAM_TEST_PIPELINE_OPTIONS\n              + \":\"\n              + System.getProperty(PROPERTY_BEAM_TEST_PIPELINE_OPTIONS),\n          e);\n    }\n  }\n\n  /** Like {@link #run} but with the given potentially modified options. */\n  @Override\n  public PipelineResult run(PipelineOptions options) {\n    checkState(\n        enforcement.isPresent(),\n        \"Is your TestPipeline declaration missing a @Rule annotation? Usage: \"\n            + \"@Rule public final transient TestPipeline pipeline = TestPipeline.create();\");\n\n    final PipelineResult pipelineResult;\n    try {","sourceCodeStart":399,"sourceCodeEnd":435,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/core/src/main/java/org/apache/beam/sdk/testing/TestPipeline.java#L399-L435","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Print and validate the property value; ensure it is valid JSON, e.g. [\"--runner=DirectRunner\"].","Confirm every option name matches the current PipelineOptions class (check for renames in your Beam version).","Ensure the runner/options classes are on the test classpath.","Set the property in the build config with correct escaping (single quotes around the JSON in Maven surefire argLine)."],"exampleFix":"// before (Maven argLine)\n-DbeamTestPipelineOptions=[--runner=DirectRunner]\n// after\n-DbeamTestPipelineOptions=[\\\"--runner=DirectRunner\\\"]","handlingStrategy":"validation","validationCode":"String opts = System.getProperty(\"beamTestPipelineOptions\"); if (opts == null || !opts.trim().startsWith(\"[\")) { throw new IllegalStateException(\"beamTestPipelineOptions must be a JSON array of strings\"); }","typeGuard":null,"tryCatchPattern":"try { pipeline.run(); } catch (RuntimeException e) { if (e.getMessage().startsWith(\"Unable to instantiate test options\")) { /* fix the JSON in the system property */ } }","preventionTips":["Keep the property value as strict JSON, e.g. [\"--runner=DirectRunner\"].","Escape quotes correctly in Maven/Gradle configs.","Validate option names against your Beam version's PipelineOptions.","Ensure runner classes are on the test classpath."],"tags":["java","configuration","apache-beam","system-properties"],"backgroundTag":"invalid-config-value","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"}