{"record":{"id":"7639f719253cabaa","repo":"apache/beam","slug":"cannot-call-run-pipeline-on-an-instance-of-s-s-should-only","errorCode":null,"errorMessage":"Cannot call #run(Pipeline) on an instance of %s. %s should only be used as the default to construct a Pipeline using %s, and cannot execute Pipelines. Instead, specify a %s by providing PipelineOptions in the system property '%s'.","messagePattern":"Cannot call #run\\(Pipeline\\) on an instance of (.+?)\\. (.+?) should only be used as the default to construct a Pipeline using (.+?), and cannot execute Pipelines\\. Instead, specify a (.+?) by providing PipelineOptions in the system property '(.+?)'\\.","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"critical","filePath":"sdks/java/core/src/main/java/org/apache/beam/sdk/testing/CrashingRunner.java","lineNumber":38,"sourceCode":"import org.apache.beam.sdk.Pipeline;\nimport org.apache.beam.sdk.PipelineResult;\nimport org.apache.beam.sdk.PipelineRunner;\nimport org.apache.beam.sdk.options.PipelineOptions;\n\n/**\n * A {@link PipelineRunner} that applies no overrides and throws an exception on calls to {@link\n * Pipeline#run()}. For use in {@link TestPipeline} to construct but not execute pipelines.\n */\npublic final class CrashingRunner extends PipelineRunner<PipelineResult> {\n\n  @SuppressWarnings(\"unused\") // used by reflection\n  public static CrashingRunner fromOptions(PipelineOptions opts) {\n    return new CrashingRunner();\n  }\n\n  @Override\n  public PipelineResult run(Pipeline pipeline) {\n    throw new IllegalArgumentException(\n        String.format(\n            \"Cannot call #run(Pipeline) on an instance \"\n                + \"of %s. %s should only be used as the default to construct a Pipeline \"\n                + \"using %s, and cannot execute Pipelines. Instead, specify a %s \"\n                + \"by providing PipelineOptions in the system property '%s'.\",\n            CrashingRunner.class.getSimpleName(),\n            CrashingRunner.class.getSimpleName(),\n            TestPipeline.class.getSimpleName(),\n            PipelineRunner.class.getSimpleName(),\n            TestPipeline.PROPERTY_BEAM_TEST_PIPELINE_OPTIONS));\n  }\n}\n","sourceCodeStart":20,"sourceCodeEnd":51,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/core/src/main/java/org/apache/beam/sdk/testing/CrashingRunner.java#L20-L51","documentation":"CrashingRunner is Beam's default PipelineRunner that exists only to fail fast: any attempt to actually run a Pipeline throws this IllegalArgumentException. It indicates that no real runner (DirectRunner, FlinkRunner, DataflowRunner, ...) was configured, so PipelineOptions still carries the default CrashingRunner.","triggerScenarios":"Calling Pipeline.run() (which delegates to CrashingRunner.run) without setting a real runner — i.e. no `--runner=` option and no `PipelineOptionsFactory`-registered runner; or explicitly instantiating CrashingRunner and calling run(Pipeline).","commonSituations":"Running a Beam job from an IDE or test harness without passing the `runner` system property; building a pipeline for serialization/inspection only and forgetting to swap in a real runner before execution; CI environments missing the runner option.","solutions":["Set a real runner via PipelineOptions, e.g. `--runner=DirectRunner` or System property `-Drunner=DirectRunner`","In code: `PipelineOptions opts = PipelineOptionsFactory.fromArgs(args).create(); opts.setRunner(DirectRunner.class);`","If the pipeline is only meant for graph construction, do not call run(); use Pipeline.apply/merge only or GraphSurgeon-style tools"],"exampleFix":"// before\nPipeline p = Pipeline.create(PipelineOptionsFactory.create());\np.run();\n// after\nPipelineOptions opts = PipelineOptionsFactory.fromArgs(\"--runner=DirectRunner\").create();\nPipeline p = Pipeline.create(opts);\np.run().waitUntilFinish();","handlingStrategy":"validation","validationCode":"if (PipelineOptionsFactory.create().getRunner().equals(CrashingRunner.class)) {\n  throw new IllegalStateException(\"No real runner configured; pass --runner=<Runner> or -Drunner=\");\n}","typeGuard":"boolean hasRealRunner(PipelineOptions opts) {\n  return opts.getRunner() != null && !CrashingRunner.class.equals(opts.getRunner());\n}","tryCatchPattern":"try {\n  pipeline.run().waitUntilFinish();\n} catch (IllegalArgumentException e) {\n  if (e.getMessage().contains(\"CrashingRunner\")) {\n    throw new IllegalStateException(\"Configure a real runner, e.g. --runner=DirectRunner\", e);\n  }\n  throw e;\n}","preventionTips":["Always pass --runner=<DirectRunner|DataflowRunner|...> in args, system properties, or set options.setRunner(...) programmatically","Never leave CrashingRunner as the runner in executable pipelines; it is only a safe default for construction-only usage","Add a unit test asserting PipelineOptionsFactory.create().getRunner() != CrashingRunner.class in launch scripts"],"tags":["apache-beam","pipeline-runner","configuration","directrunner"],"backgroundTag":"missing-required-config-value","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-20T03:17:13.778Z"}