apache/beam · error · PopulateDisplayDataException

Error while populating display data for component

Error message

Error while populating display data for component '%s': %s

What it means

Beam throws this when a component's populateDisplayData(DisplayData.Builder) callback throws any Throwable. DisplayData is collected for pipeline introspection (UIs, monitoring), and Beam wraps the failure in PopulateDisplayDataException, naming the failing component namespace and its message, so pipeline construction surfaces which component had bad display-data logic.

Solutions

Fix the exception thrown inside the component's populateDisplayData method (see the wrapped cause e).
Guard nullable fields with DisplayData.Builder methods that tolerate null, or use valueOf(..., null ok variants).
Wrap risky display-data computation in try/catch inside populateDisplayData and register a static string instead.

Example fix

// before
public void populateDisplayData(DisplayData.Builder builder) {
  builder.add(DisplayData.item("path", config.getPath().toString())); // NPE if path null
}
// after
public void populateDisplayData(DisplayData.Builder builder) {
  builder.add(DisplayData.item("path", String.valueOf(config.getPath())));
}

Defensive patterns

Strategy: try-catch

Validate before calling

// Verify display data collection succeeds during pipeline construction/testing:
DisplayData.from(myTransform); // throws PopulateDisplayDataException early if broken

Type guard

boolean hasSafeDisplayData(PTransform<?,?> t) {
  try { DisplayData.from(t); return true; } catch (Exception e) { return false; }
}

Try / catch

try {
  DisplayData.from(transform);
} catch (PopulateDisplayDataException e) {
  LOG.error("Display data failed for component", e.getCause());
}

Prevention

Never dereference nullable fields directly in populateDisplayData
Use String.valueOf or null-tolerant DisplayData.item builders
Exercise DisplayData.from() in unit tests of custom transforms

When it happens

Trigger: A Transform (PTransform/DoFn/etc.) implements populateDisplayData and throws inside it — e.g. dereferencing a null field, calling a getter that throws, or formatting logic that fails — while DisplayData.collect() walks the component tree.

Common situations: Custom transforms that compute display data from mutable/nullable state; SDK internal components after upgrades; display data code reading external config files that are missing at graph-construction time.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

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

Appendix: source

Thrown at sdks/java/core/src/main/java/org/apache/beam/sdk/transforms/display/DisplayData.java:792

      Path prevPath = latestPath;
      Class<?> prevNs = latestNs;
      latestPath = path;
      latestNs = namespace;

      try {
        subComponent.populateDisplayData(this);
      } catch (PopulateDisplayDataException e) {
        // Don't re-wrap exceptions recursively.
        throw e;
      } catch (OutOfMemoryError oom) {
        throw oom;
      } catch (Throwable e) {
        String msg =
            String.format(
                "Error while populating display data for component '%s': %s",
                namespace.getName(), e.getMessage());
        throw new PopulateDisplayDataException(msg, e);
      }

      latestPath = prevPath;
      latestNs = prevNs;

      return this;
    }

    /** Marker exception class for exceptions encountered while populating display data. */
    private static class PopulateDisplayDataException extends RuntimeException {
      PopulateDisplayDataException(String message, Throwable cause) {
        super(message, cause);
      }
    }

    @Override
    public Builder add(ItemSpec<?> item) {
      checkNotNull(item, "Input display item cannot be null");

View on GitHub (pinned to 12126d8942)