temporalio/temporal · error

unable to encode payloads: %v

Error message

unable to encode payloads: %v

What it means

MustEncode encodes multiple values into Payloads via the default data converter and panics on error, matching Go's Must* convention where the caller explicitly opts into panic-on-failure. Failures stem from values the converter cannot serialize.

Source

Thrown at common/payloads/payloads.go:59

	}
	if len(ps.GetPayloads()) < 1 {
		return nil, nil
	}
	return ps.GetPayloads()[0], nil
}

func MustEncodeSingle(value any) *commonpb.Payload {
	p, err := EncodeSingle(value)
	if err != nil {
		panic(fmt.Sprintf("unable to encode single payload: %v", err)) //nolint:forbidigo // Must-helper: callers opt into panic on encode failure
	}
	return p
}

func MustEncode(value ...any) *commonpb.Payloads {
	p, err := defaultDataConverter.ToPayloads(value...)
	if err != nil {
		panic(fmt.Sprintf("unable to encode payloads: %v", err)) //nolint:forbidigo // Must-helper: callers opt into panic on encode failure
	}
	return p
}

func Decode(ps *commonpb.Payloads, valuePtr ...any) error {
	return defaultDataConverter.FromPayloads(ps, valuePtr...)
}

func ToString(ps *commonpb.Payloads) string {
	return fmt.Sprintf("[%s]", strings.Join(defaultDataConverter.ToStrings(ps), ", "))
}

View on GitHub (pinned to bde624efd1)

Solutions

1. Inspect the panic message to identify which value failed and why
2. Switch to the error-returning payloads.Encode for fallible inputs
3. Ensure all encoded types are supported by the configured data converter (add struct tags or a custom converter)
4. Validate test fixtures for nil/unsupported values

Example fix

// before
pl := payloads.MustEncode(arg) // panics on unsupported type
// after
pl, err := payloads.Encode(arg)
if err != nil {
	return fmt.Errorf("encode payloads: %w", err)
}

func canEncodeAll(vs ...any) bool { _, err := payloads.Encode(vs...); return err == nil }

defer func() {
	if r := recover(); r != nil {
		logger.Error("MustEncode panicked", r)
		err = fmt.Errorf("payloads encode failed: %v", r)
	}
}() // around the MustEncode call

When it happens

Trigger: Calling MustEncode with at least one unencodable value (unsupported type, nil, function/channel/map key the JSON/proto converter rejects).

Common situations: Passing structs lacking JSON tags when the JSON converter is active; encoding arguments with unexported-only fields that fail round-trip expectations; tests with malformed fixtures.

Related errors

• unable to encode single payload: %v
• panic(err)
• Current cluster name is empty
• Version increment <= 0 or > 2147483647
• <dynamic updateVersionToClusterName err>

AI-assisted analysis of temporalio/temporal@bde624efd1 (2026-09-01). Data as JSON: /api/errors/01cd822f8cb13de9. Report an issue: GitHub.