apache/beam · warning · java.lang.IllegalStateException

name not set

Error message

name not set

What it means

PValueBase.getName() throws IllegalStateException when the PValue's name has never been assigned. Every PTransform/PCollection has a name that Beam sets during pipeline construction; querying it before naming (or after constructing a bare PValue) fails. Frequently surfaced indirectly through toString().

Solutions

1. Ensure the value comes from pipeline.apply(...) so Beam assigns a default name.
2. Call setName(...) explicitly on the PValue before using getName().
3. In logging, guard with try-catch or print the class identity instead of relying on getName().
4. For custom sources/sinks, invoke setName in the constructor or builder.

Example fix

// before
PCollection<Integer> pc = new PCollection<>(...);
System.out.println(pc.getName()); // IllegalStateException: name not set
// after
PCollection<Integer> pc = new PCollection<>(...);
pc.setName("my-collection");
System.out.println(pc.getName());

if (pvalue instanceof PValueBase) {
  try { ((PValueBase) pvalue).getName(); } catch (IllegalStateException e) { /* unnamed */ }
}

static boolean hasName(PValue v) {
  try { v.getName(); return true; } catch (IllegalStateException e) { return false; }
}

try {
  log(name.getName());
} catch (IllegalStateException e) {
  log("<unnamed>" + name.getClass().getSimpleName());
}

When it happens

Trigger: Calling getName() (or toString()/display data paths that call it) on a PValue created outside a normal apply() chain, or before the pipeline has assigned the name (name == null).

Common situations: Debug logging that calls pvalue.toString() on a hand-constructed PCollection/PValue in tests; building custom PValues without calling setName(); inspecting values before pipeline assembly completes.

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

Related errors

• A PValue contained in
• Cannot call getFromRowFunction when there is no schema
• Cannot call getSchema when there is no schema
• Cannot call getToRowFunction when there is no schema
• Error collections cannot be added after Error Handler is…

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

Appendix: source

Thrown at sdks/java/core/src/main/java/org/apache/beam/sdk/values/PValueBase.java:51

 * PValue}.
 */
@Internal
public abstract class PValueBase implements PValue {

  private final transient @Nullable Pipeline pipeline;

  /**
   * Returns the name of this {@link PValueBase}.
   *
   * <p>By default, the name of a {@link PValueBase} is based on the name of the {@link PTransform}
   * that produces it. It can be specified explicitly by calling {@link #setName}.
   *
   * @throws IllegalStateException if the name hasn't been set yet
   */
  @Override
  public String getName() {
    if (name == null) {
      throw new IllegalStateException("name not set");
    }
    return name;
  }

  /**
   * Sets the name of this {@link PValueBase}. Returns {@code this}.
   *
   * @throws IllegalStateException if this {@link PValueBase} has already been finalized and may no
   *     longer be set.
   */
  public PValueBase setName(String name) {
    checkState(!finishedSpecifying, "cannot change the name of %s once it's been used", this);
    this.name = name;
    return this;
  }

  /////////////////////////////////////////////////////////////////////////////

View on GitHub (pinned to 12126d8942)