apache/beam · error · IllegalStateException

Error while prepareRun

Error message

Error while prepareRun

What it means

Plugin.prepareRun() delegates to the CDAP plugin's prepareRun(context). Any exception thrown by the plugin during preparation (authentication, connection, config validation) is caught, logged, and rethrown as IllegalStateException('Error while prepareRun') with the original cause attached.

Solutions

1. Inspect the wrapped cause exception in the stack trace for the real failure.
2. Validate plugin configuration (host, port, auth token, dataset names) before running the pipeline.
3. Test connectivity to the CDAP instance with curl or the CDAP CLI.
4. Fix authentication/authorization credentials if the cause indicates auth errors.

// pre-flight: validate plugin config and connectivity
Curl/CDAP CLI check: curl -H 'Authorization: Bearer $TOKEN' https://$CDAP_HOST:$PORT/v3/namespaces

try { pipeline.run().waitUntilFinish(); } catch (IllegalStateException e) {
  if ("Error while prepareRun".equals(e.getMessage())) {
    Throwable cause = e.getCause(); // real plugin failure
  }
  throw e;
}

When it happens

Trigger: Calling CdapIO.read()/write() where the underlying plugin's prepareRun fails — e.g. bad credentials, unreachable instance, invalid plugin configuration.

Common situations: Wrong CDAP instance host/port/token; expired credentials; invalid plugin config values discovered during preparation; network/timeout to CDAP instance.

Understand the failure class

Background: "API request failed": what wrapped HTTP errors from external APIs mean and how to find the real cause — this error's family across 29 libraries.

Related errors

• Can not call prepareRun
• Could not get value Coder
• Given plugin class ' ' is not supported!
• Support for unbounded plugins is not implemented!
• A function must be provided to convert the input type into…

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

Appendix: source

Thrown at sdks/java/io/cdap/src/main/java/org/apache/beam/sdk/io/cdap/Plugin.java:121

  /**
   * Calls {@link SubmitterLifecycle#prepareRun(Object)} method on the {@link #cdapPluginObj}
   * passing needed {@param config} configuration object as a parameter. This method is needed for
   * validating connection to the CDAP sink/source and performing initial tuning.
   */
  public void prepareRun() {
    if (isUnbounded()) {
      // Not needed for unbounded plugins
      return;
    }
    if (cdapPluginObj == null) {
      instantiateCdapPluginObj();
    }
    checkStateNotNull(cdapPluginObj, "Cdap Plugin object can't be null!");
    try {
      cdapPluginObj.prepareRun(getContext());
    } catch (Exception e) {
      LOG.error("Error while prepareRun", e);
      throw new IllegalStateException("Error while prepareRun", e);
    }
    if (getPluginType().equals(PluginConstants.PluginType.SOURCE)) {
      for (Map.Entry<String, String> entry :
          getContext().getInputFormatProvider().getInputFormatConfiguration().entrySet()) {
        getHadoopConfiguration().set(entry.getKey(), entry.getValue());
      }
    } else {
      for (Map.Entry<String, String> entry :
          getContext().getOutputFormatProvider().getOutputFormatConfiguration().entrySet()) {
        getHadoopConfiguration().set(entry.getKey(), entry.getValue());
      }
      getHadoopConfiguration().set(MRJobConfig.ID, String.valueOf(1));
    }
  }

  /** Creates an instance of {@link #cdapPluginObj} using {@link #pluginConfig}. */
  private void instantiateCdapPluginObj() {
    PluginConfig pluginConfig = getPluginConfig();

View on GitHub (pinned to 12126d8942)