apache/beam · error

unknown logical type

Error message

unknown logical type: %v

What it means

Returned by fieldTypeToReflectType when a FieldType has a LogicalType whose URN is not a key in the registry r.logicalTypes. The Go SDK can only materialize logical types that have been explicitly mapped to a Go type. Unknown URNs make the Go struct representation impossible, so the conversion aborts.

Solutions

1. Register the logical type via schema.RegisterLogicalType with a matching URN implementing the LogicalType interface
2. Upgrade the Beam Go SDK to a version that knows the built-in URN in question
3. Change the pipeline to emit a plain primitive or RowType instead of the custom logical type
4. Print/log available registered URNs to confirm the missing identifier

Example fix

// before
type Money struct{} // no registration; URN "myco:money" unknown to Go
// after
type MoneyLogicalType struct{}
func (MoneyLogicalType) Urn() string { return "myco:money" }
func (MoneyLogicalType) GoType() reflect.Type { return reflect.TypeOf(Money{}) }
func init() { schema.RegisterLogicalType(MoneyLogicalType{}) }

if _, ok := registry[urn]; !ok {
  return fmt.Errorf("logical type %q not registered; call schema.RegisterLogicalType in init()", urn)
}

func logicalTypeRegistered(urn string, r *Representer) bool {
  _, ok := r.logicalTypes[urn]
  return ok
}

lt, err := resolveLogicalType(urn)
if err != nil {
  if isUnknownURN(err) { registerMissing(urn); lt, err = resolveLogicalType(urn) }
  if err != nil { return err }
}

When it happens

Trigger: Decoding a schema containing *pipepb.FieldType_LogicalType with a URN absent from r.logicalTypes — typical for custom logical types from Python/Java, or newer built-in logical types when running an older Go SDK.

Common situations: Cross-language pipelines emitting custom logical types (e.g. Python LogicalType subclasses); Beam version mismatch where the writer SDK emits a logical type the reader Go SDK predates; forgotten schema.RegisterLogicalType call in the worker main.

Related errors

• unable to convert LogicalType
• beam.RegisterSchemaProvider: schema type provider for
• can't generate row coder for type
• cannot make schema for type
• decoding a *

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

Appendix: source

Thrown at sdks/go/pkg/beam/core/runtime/graphx/schema/schema.go:799

		if err != nil {
			return nil, errors.Wrap(err, "unable to convert map value type")
		}
		t = reflect.MapOf(kt, vt) // Panics for invalid map keys (slices/iterables)
	case *pipepb.FieldType_RowType:
		rt, err := r.toType(sft.GetRowType().GetSchema())
		if err != nil {
			return nil, errors.Wrapf(err, "unable to convert row type: %v", sft.GetRowType().GetSchema().GetId())
		}
		t = rt
	// case *pipepb.FieldType_IterableType:
	// TODO(BEAM-9615): handle IterableTypes (eg. CoGBK values)

	case *pipepb.FieldType_LogicalType:
		lst := sft.GetLogicalType()
		identifier := lst.GetUrn()
		lt, ok := r.logicalTypes[identifier]
		if !ok {
			return nil, errors.Errorf("unknown logical type: %v", identifier)
		}
		t = lt.GoType()

	default:
		return nil, errors.Errorf("unknown fieldtype: %T", sft.GetTypeInfo())
	}
	if sft.GetNullable() {
		return reflect.PtrTo(t), nil
	}
	return t, nil
}

// parseTag splits a struct field's beam tag into its name and
// comma-separated options.
func parseTag(tag string) (string, options) {
	if idx := strings.Index(tag, ","); idx != -1 {
		return tag[:idx], options(tag[idx+1:])
	}

View on GitHub (pinned to 12126d8942)