apache/beam · error

Unexpected opt

Error message

Unexpected opt: %v

What it means

parseOpts inspects each variadic Option passed to a Beam transform and only recognizes SideInput and TypeDefinition option types. Any other option implementation reaches the default case and panics with 'Unexpected opt: %v'. It signals that an Option type is not supported at the point where beam validates the transform.

Solutions

1. Remove or replace the unsupported option with one of the accepted types (SideInput or TypeDefinition)
2. Check the Beam version/docs for the correct option helper for the transform being used
3. If implementing a custom Option, register/handle it in parseOpts or use a supported extension point instead

Example fix

// before
beam.ParDo(s, dofn, col, myCustomOpt{}) // panics: Unexpected opt
// after
beam.ParDo(s, dofn, col) // only supported opts

for _, opt := range opts {
    switch opt.(type) {
    case beam.SideInput, beam.TypeDefinition:
    default:
        return fmt.Errorf("unsupported option %T", opt)
    }
}

func isSupportedOpt(o beam.Option) bool {
    switch o.(type) {
    case beam.SideInput, beam.TypeDefinition:
        return true
    }
    return false
}

defer func() {
    if r := recover(); r != nil {
        err = fmt.Errorf("beam option rejected: %v", r)
    }
}()

When it happens

Trigger: Passing an Option value that is neither SideInput nor TypeDefinition into a beam transform (e.g. beam.ParDo/beam.Impulse paths that call validate -> parseOpts), typically a custom or newly introduced Option type.

Common situations: A developer implements the Option interface themselves, or uses an option exported for a different transform family, or upgrades Beam where an option stopped being handled in parseOpts.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

• couldn't decode characteristic for variant
• Creating CustomCoder for type failed
• empty slice passed as an argument to trigger.AfterAny()
• err
• error decoding append bag user state window key

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

Appendix: source

Thrown at sdks/go/pkg/beam/option.go:63

	Var reflect.Type
	// T is the type it is bound to.
	T reflect.Type
}

func (s TypeDefinition) private() {}

func parseOpts(opts []Option) ([]SideInput, []TypeDefinition) {
	var side []SideInput
	var infer []TypeDefinition

	for _, opt := range opts {
		switch opt := opt.(type) {
		case SideInput:
			side = append(side, opt)
		case TypeDefinition:
			infer = append(infer, opt)
		default:
			panic(fmt.Sprintf("Unexpected opt: %v", opt))
		}
	}
	return side, infer
}

View on GitHub (pinned to 12126d8942)