apache/beam · error · RuntimeException

Error decoding payload

Error message

Error decoding payload

What it means

decodeRow wraps IOException from RowCoder.of(payloadSchema).decode in a RuntimeException 'Error decoding payload': the byte payload could not be decoded into a Row matching payloadSchema (corrupt/truncated bytes or schema mismatch).

Source

Thrown at sdks/java/expansion-service/src/main/java/org/apache/beam/sdk/expansion/service/JavaClassLookupTransformProvider.java:623

        throw new IllegalArgumentException("Wildcard builder not allowed for non-wildcard class.");
      }
      return new AutoValue_JavaClassLookupTransformProvider_AllowedClass(
          className, allowedBuilderMethods, allowedConstructorMethods);
    }
  }

  static Row decodeRow(SchemaApi.Schema schema, ByteString payload) {
    Schema payloadSchema = SchemaTranslation.schemaFromProto(schema);

    if (payloadSchema.getFieldCount() == 0) {
      return Row.withSchema(Schema.of()).build();
    }

    Row row;
    try {
      row = RowCoder.of(payloadSchema).decode(payload.newInput());
    } catch (IOException e) {
      throw new RuntimeException("Error decoding payload", e);
    }
    return row;
  }
}

View on GitHub (pinned to 12126d8942)

Solutions

1. Ensure client SDK and expansion service use the same Beam version so payload schemas match.
2. Inspect the chained IOException cause for the exact decode failure.
3. Re-encode the payload with RowCoder.of(payloadSchema) on the client and retry.
4. Log payload size and schema field names on both sides to spot truncation/schema drift.

Example fix

// before
Row row = RowCoder.of(oldSchema).decode(payload.newInput());
// after
Row row = RowCoder.of(payloadSchema).decode(payload.newInput()); // matching encoder schema

if (payload == null || payload.size() == 0) throw new IllegalArgumentException("Empty payload for row decode");

try { Row row = decodeRow(payload); } catch (RuntimeException e) { log.error("Payload decode failed (size=" + payload.size() + ")", e); throw new PayloadDecodeException(e); }

When it happens

Trigger: Decoding a FunctionSpec payload (constructorRow/builderMethodRow) when payload bytes were produced with a different schema, truncated in transport, or encoded by an incompatible SDK version.

Common situations: Version skew between client SDK and expansion service; hand-built or edited payloads; schema drift after Beam upgrade.

Understand the failure class

Background: "cannot parse invalid wire-format data", "cannot unmarshal", "failed unmarshalling": protobuf unmarshal errors explained — this error's family across 10 libraries.

Related errors

• unexpected extra bytes after decoding
• ReadSimpleRowHeader reading nils count: %v, %v
• ReadSimpleRowHeader expected no nils encoded count, got %v
• error decoding []byte field
• invalid float encoding for: %v

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