method has invalid return values, only allowed an optional…

Error message

method %v has invalid return values, only allowed an optional error

What it means

Error raised in AsDoFn's post-validation: one of the lifecycle methods (Setup, StartBundle, FinishBundle, or Teardown) declares return values other than the single optional error. These lifecycle methods must return nothing or just error; any other return type on them is rejected with this message naming the offending method.

Solutions

Change the method to return nothing or only error
Emit data through emit funcs on ProcessElement, not lifecycle returns
Log diagnostics instead of returning non-error values

Example fix

// before
func (f *MyFn) StartBundle(ctx context.Context) int { ... }
// after
func (f *MyFn) StartBundle(ctx context.Context) error { ... }

Defensive patterns

Strategy: validation

Validate before calling

for _, name := range []string{"Setup", "StartBundle", "FinishBundle", "Teardown"} {
  m, ok := reflect.TypeOf(fn).MethodByName(name)
  if !ok { continue }
  t := m.Type
  if t.NumOut() > 1 || (t.NumOut() == 1 && t.Out(0) != reflect.TypeOf((*error)(nil)).Elem()) {
    return fmt.Errorf("%s must return nothing or error", name)
  }
}

Prevention

Return only error (or nothing) from lifecycle methods
Never use lifecycle returns to pass data downstream

When it happens

Trigger: Declaring e.g. Setup() context.Context, StartBundle() (int, error), or FinishBundle() string, then constructing the DoFn.

Common situations: Attempting to emit results from StartBundle/FinishBundle via return values instead of the emit function parameter on ProcessElement; returning diagnostics other than error.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

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

Appendix: source

Thrown at sdks/go/pkg/beam/core/graph/fn.go:597

					"method %v has invalid parameters, "+
						"only allowed an optional context.Context", name)
				err = errors.SetTopLevelMsgf(err,
					"Method %v of DoFns should have no parameters other than "+
						"an optional context.Context, but invalid parameters are "+
						"present in DoFn %v.",
					name, fn.Name())
				return nil, addContext(err, fn)
			}
		}
	}

	// Check that none of the methods (except ProcessElement) have any return
	// values other than error.
	for _, name := range []string{setupName, startBundleName, finishBundleName, teardownName} {
		if method, ok := fn.methods[name]; ok {
			returns := method.Ret
			if len(returns) > 1 || (len(returns) == 1 && returns[0].Kind != funcx.RetError) {
				err := errors.Errorf(
					"method %v has invalid return values, "+
						"only allowed an optional error", name)
				err = errors.SetTopLevelMsgf(err,
					"Method %v of DoFns should have no return values other "+
						"than an optional error, but invalid return values are present "+
						"in DoFn %v.",
					name, fn.Name())
				return nil, addContext(err, fn)
			}
		}
	}

	// Check whether to perform SDF validation.
	isSdf, err := validateIsSdf(fn)
	if err != nil {
		return nil, addContext(err, fn)
	}

View on GitHub (pinned to 12126d8942)