TruncateRestriction has unexpected number of return values:

Error message

TruncateRestriction has unexpected number of return values: %v

What it means

The SDF invoker requires TruncateRestriction to return either 1 value (the truncated restriction) or 2 values (restriction + error). Other arities hit the panic fallback in the generated dispatcher. This method is optional for SDFs but must follow the arity contract when present.

Source

Thrown at sdks/go/pkg/beam/core/runtime/exec/sdf_invokers_arity.tmpl:241

	{{end}}
{{end}}
{{end}}
	default:
		if len(n.fn.Param) < 2 || len(n.fn.Param) > 4 {
			return errors.Errorf("TruncateRestriction has unexpected number of parameters: %v", len(n.fn.Param))
		}

		n.call = func() (rest any, err error) {
			ret := n.fn.Fn.Call(n.args)

			switch len(ret) {
			case 1:
				return ret[0], nil
			case 2:
				return ret[0], asError(ret[1])
			}

			panic(fmt.Sprintf("TruncateRestriction has unexpected number of return values: %v", len(ret)))
		}
	}

	return nil
}

View on GitHub (pinned to 12126d8942)

Solutions

Make TruncateRestriction return exactly (Rest) or (Rest, error)
If truncation isn't needed, remove the method entirely (it's optional) rather than keep a wrong signature
Validate the signature against Beam SDF documentation

Example fix

// before
func (fn *sdfFn) TruncateRestriction(r Rest, b bool) (Rest, bool, error) { ... }

// after
func (fn *sdfFn) TruncateRestriction(r Rest) (Rest, error) { ... }

Defensive patterns

Strategy: validation

Validate before calling

m := reflect.ValueOf(fn).MethodByName("TruncateRestriction")
if m.IsValid() && m.Type().NumOut() != 1 && m.Type().NumOut() != 2 {
    return fmt.Errorf("TruncateRestriction must return 1 or 2 values")
}

Type guard

func validTruncateRestriction(fn interface{}) bool {
    m := reflect.ValueOf(fn).MethodByName("TruncateRestriction")
    if !m.IsValid() { return true } // optional method
    n := m.Type().NumOut()
    return n == 1 || n == 2
}

Try / catch

defer func() {
    if r := recover(); strings.Contains(fmt.Sprint(r), "TruncateRestriction has unexpected number of return values") {
        log.Fatalf("SDF signature error: %v", r)
    }
}()

Prevention

Return (rest) or (rest, error) — nothing else
Remove the method if truncation support isn't needed
Test drain behavior on a small streaming pipeline before production

When it happens

Trigger: Implementing TruncateRestriction with 0 or 3+ return values on a splittable DoFn and running a pipeline where truncation (e.g., drain) is invoked.

Common situations: Draining a streaming pipeline with a malformed TruncateRestriction; refactoring the method and changing its return count.

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/8380e6f7e09fb7fb. Report an issue: GitHub.