What causes "Unknown type of decoding context" in apache/beam?

Pass a longer, more specific substring that uniquely matches one identifier (e.g. 'kafka_read' instead of 'kafka').

Unknown type of decoding context

Error message

Unknown type of decoding context

What it means

discover_config raises ValueError when the substring name matches more than one SchemaTransform identifier in the expansion service catalog. Because it returns a single config, ambiguity is treated as an error and the matching identifiers are listed in the message. The developer must supply a more specific name.

Source

Thrown at sdks/typescript/src/apache_beam/coders/required_coders.ts:123

   *
   * If the context is `wholeStream`, the whole input stream is decoded as-is.
   *
   * @param reader - a reader to access the input byte stream
   * @param context - whether the data is encoded with delimiters (`Context.needsDelimiters`), or without (`Context.wholeStream`).
   * @returns
   */
  decode(reader: Reader, context: Context): Uint8Array {
    switch (context) {
      case Context.wholeStream:
        return reader.buf.slice(reader.pos);
        break;
      case Context.needsDelimiters:
        var length = reader.int32();
        var value = reader.buf.slice(reader.pos, reader.pos + length);
        reader.pos += length;
        return value;
      default:
        throw new Error("Unknown type of decoding context");
    }
  }

  toProto(pipelineContext: ProtoContext): runnerApi.Coder {
    return {
      spec: {
        urn: BytesCoder.URN,
        payload: new Uint8Array(),
      },
      componentCoderIds: [],
    };
  }
}

globalRegistry().register(BytesCoder.URN, BytesCoder);

/**
 * A coder for a key-value pair.

View on GitHub (pinned to 12126d8942)

Solutions

Pass a longer, more specific substring that uniquely matches one identifier (e.g. 'kafka_read' instead of 'kafka').
Read the identifiers listed in the error and pick the exact one.
Use the fully qualified identifier if the API accepts it.

Example fix

// before
SchemaTransforms.discover_config('kafka')  # matches kafka_read and kafka_write
// after
SchemaTransforms.discover_config('kafka_read')

Defensive patterns

Strategy: validation

Validate before calling

matches = [i for i in identifiers if name in i]
assert len(matches) == 1, f'ambiguous: {matches}'

Type guard

def is_unambiguous(name: str, identifiers: list[str]) -> bool:
    return len([i for i in identifiers if name in i]) == 1

Try / catch

try:
    cfg = SchemaTransforms.discover_config(name)
except ValueError as e:
    identifiers = parse_listed_ids(e)
    cfg = SchemaTransforms.discover_config(longest(ids_with(name, identifiers)))

Prevention

Always use the longest distinctive substring of the identifier
Avoid generic fragments like 'read' or 'write'
Read the ambiguous identifier list in the message and pick exactly one

When it happens

Trigger: Calling discover_config with a short or generic substring that matches several identifiers, e.g. discover_config('kafka') matching both kafka_read and kafka_write, or discover_config('read').

Common situations: Using broad substrings like 'read', 'write', 'bigquery' when multiple versions/variants of a transform exist; versioned URNs (v1/v2) both matching one substring.

Related errors

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