TruncateRestriction has unexpected number of return values

Error message

TruncateRestriction has unexpected number of return values: %v

What it means

The reflection invoker for the SDF method TruncateRestriction expects either (truncatedRestriction) or (truncatedRestriction, error) return values. Any other arity causes this panic. Truncation is used for drain scenarios, so the contract violation is caught when the runtime invokes the method.

Solutions

Return exactly the truncated restriction, e.g. (MyRestriction)
Or (MyRestriction, error) if truncation can fail
Match the restriction type to the one produced by CreateInitialRestriction
Verify signatures against the sdf package's documented lifecycle methods

Example fix

// before
func (fn *MyDoFn) TruncateRestriction(r MyRestriction) (MyRestriction, string, error) { ... }
// after
func (fn *MyDoFn) TruncateRestriction(r MyRestriction) (MyRestriction, error) { ... }

Defensive patterns

Strategy: validation

Validate before calling

t := reflect.TypeOf(fn.TruncateRestriction)
if t.NumOut() != 1 && t.NumOut() != 2 {
    panic("TruncateRestriction must return (R) or (R, error)")
}

Type guard

func validArity(m interface{}) bool {
    n := reflect.TypeOf(m).NumOut()
    return n == 1 || n == 2
}

Prevention

Keep the truncated restriction type identical to the initial restriction type
Mirror the signature style of your other SDF methods
Validate with drain-mode tests before production
Only add (…, error) when truncation can genuinely fail

When it happens

Trigger: TruncateRestriction defined with 0 or 3+ return values; returning (restriction, err, log message) or similar extra outputs; method registered under the wrong reflection key.

Common situations: Implementing drain support for the first time and guessing the signature; copying from a non-Beam truncation helper; refactors that added a return value for diagnostics.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

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

Appendix: source

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

			return r0, asError(r1)
		}

	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)