unable to convert LogicalType

Error message

unable to convert LogicalType[%v]'s storage type %v for Go type of %v to a schema

What it means

Raised in Registry.logicalTypeToFieldType when a LogicalType was registered for the struct type t, but converting that logical type's StorageType() into a Beam FieldType fails. The wrap identifies the logical type ID, storage type, and Go type. It means the logical type's chosen storage representation is itself not schema-convertible.

Solutions

Inspect the wrapped error to see why the storage type fails conversion.
Change the logical type's StorageType to a schema-serializable representation (bytes, string, struct).
Re-register the logical type with a custom TypeEncoder/TypeDecoder compatible with the new storage type.
Remove the bad logical type registration if redundant.

Example fix

// before
beam.RegisterLogicalType(beam.NewLogicalTypeWithName("MyT", reflect.TypeOf(func(){}))) // bad storage
// after
beam.RegisterLogicalType(beam.NewLogicalTypeWithName("MyT", reflect.TypeOf(""))) // string storage

Defensive patterns

Strategy: validation

Validate before calling

if lID, ok := reg.HasLogicalTypeFor(reflect.TypeOf(myVal)); ok {
    // test conversion of the storage type before pipeline build
    if err := schemaSafe(logicalTypeStorageType(lID)); err != nil {
        return fmt.Errorf("logical type %s storage not convertible: %w", lID, err)
    }
}

Try / catch

schm, err := reg.FromType(t)
if err != nil && strings.Contains(err.Error(), "storage type") {
    return nil, fmt.Errorf("fix registered logical type storage: %w", err)
}

Prevention

Choose simple storage types (bytes, string, structs of primitives) for logical types.
Unit-test logical type registration plus FromType round-trips.
Pair logical types with TypeEncoder/TypeDecoder registrations.
Re-test logical types after Beam upgrades.

When it happens

Trigger: Calling FromType/structToSchema/reflectTypeToFieldType on a type with a directly-registered logical type (in logicalTypeIdentifiers) whose lt.StorageType() cannot be converted by reflectTypeToFieldType (e.g. storage is a func, chan, or contains nested unsupported kinds).

Common situations: Custom logical types registered with exotic storage types; a Beam upgrade making a previously-convertible storage type unsupported; nested logical types failing recursively.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

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

Appendix: source

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

// Returns an error if the type cannot be converted to a Schema.
func (r *Registry) FromType(ot reflect.Type) (*pipepb.Schema, error) {
	if err := r.reconcileRegistrations(); err != nil {
		return nil, errors.Wrap(err, "reconciling for FromType")
	}
	if reflectx.SkipPtr(ot).Kind() != reflect.Struct {
		return nil, errors.Errorf("cannot convert %v to schema. FromType only converts structs to schemas", ot)
	}
	return r.fromType(ot)
}

func (r *Registry) logicalTypeToFieldType(t reflect.Type) (*pipepb.FieldType, string, error) {
	// Check if a logical type was registered that matches this struct type directly
	// and if so, extract the schema from it for use.
	if lID, ok := r.logicalTypeIdentifiers[t]; ok {
		lt := r.logicalTypes[lID]
		ftype, err := r.reflectTypeToFieldType(lt.StorageType())
		if err != nil {
			return nil, "", errors.Wrapf(err, "unable to convert LogicalType[%v]'s storage type %v for Go type of %v to a schema", lID, lt.StorageType(), lt.GoType())
		}
		return ftype, lID, nil
	}
	for _, lti := range r.logicalTypeInterfaces {
		if !t.Implements(lti) {
			continue
		}
		p := r.logicalTypeProviders[lti]
		st, err := p(t)
		if err != nil {
			return nil, "", errors.Wrapf(err, "unable to convert LogicalType[%v] using provider for %v schema field", t, lti)
		}
		if st == nil {
			continue
		}
		ftype, err := r.reflectTypeToFieldType(st)
		if err != nil {
			return nil, "", errors.Wrapf(err, "unable to convert LogicalType[%v]'s storage type %v for Go type of %v to a schema", "interface", st, t)

View on GitHub (pinned to 12126d8942)