{"record":{"id":"420eadef2daa2ac0","repo":"temporalio/temporal","slug":"unable-to-encode-single-payload-v","errorCode":null,"errorMessage":"unable to encode single payload: %v","messagePattern":"unable to encode single payload: (.+?)","errorType":"panic","errorClass":null,"httpStatus":null,"severity":"error","filePath":"common/payloads/payloads.go","lineNumber":51,"sourceCode":"func Encode(value ...any) (*commonpb.Payloads, error) {\n\treturn defaultDataConverter.ToPayloads(value...)\n}\n\nfunc EncodeSingle(value any) (*commonpb.Payload, error) {\n\tps, err := defaultDataConverter.ToPayloads(value)\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\tif len(ps.GetPayloads()) < 1 {\n\t\treturn nil, nil\n\t}\n\treturn ps.GetPayloads()[0], nil\n}\n\nfunc MustEncodeSingle(value any) *commonpb.Payload {\n\tp, err := EncodeSingle(value)\n\tif err != nil {\n\t\tpanic(fmt.Sprintf(\"unable to encode single payload: %v\", err)) //nolint:forbidigo // Must-helper: callers opt into panic on encode failure\n\t}\n\treturn p\n}\n\nfunc MustEncode(value ...any) *commonpb.Payloads {\n\tp, err := defaultDataConverter.ToPayloads(value...)\n\tif err != nil {\n\t\tpanic(fmt.Sprintf(\"unable to encode payloads: %v\", err)) //nolint:forbidigo // Must-helper: callers opt into panic on encode failure\n\t}\n\treturn p\n}\n\nfunc Decode(ps *commonpb.Payloads, valuePtr ...any) error {\n\treturn defaultDataConverter.FromPayloads(ps, valuePtr...)\n}\n\nfunc ToString(ps *commonpb.Payloads) string {\n\treturn fmt.Sprintf(\"[%s]\", strings.Join(defaultDataConverter.ToStrings(ps), \", \"))","sourceCodeStart":33,"sourceCodeEnd":69,"githubUrl":"https://github.com/temporalio/temporal/blob/bde624efd13fbd3843654058db6d9c716166318b/common/payloads/payloads.go#L33-L69","documentation":"MustEncodeSingle encodes a single value using the default data converter and panics on failure, by design: the Must-prefix signals callers accept panic-on-error semantics. Encoding fails only when the value is not encodable (unsupported type, nil, or a data converter error), which with the default converter is nearly always a programming mistake.","triggerScenarios":"Passing a value that EncodeSingle cannot convert (unsupported type, unmarshalable value, nil where the converter rejects it) to MustEncodeSingle, e.g. in tests like TestHappyPath or workflow code building search-attribute-like payloads.","commonSituations":"Encoding custom structs without a registered converter; passing nil or channels/functions; swapping the default data converter for one with stricter type support.","solutions":["Check the panicked value's type: ensure it is supported by the configured data converter","Use EncodeSingle (error-returning) instead of MustEncodeSingle when the value may not be encodable","Register required payload converters/serializers if using custom types","In tests, verify the fixture value passed to MustEncodeSingle is not nil"],"exampleFix":"// before\npayload := payloads.MustEncodeSingle(customType{}) // panics if unsupported\n// after\np, err := payloads.EncodeSingle(customType{})\nif err != nil {\n\treturn fmt.Errorf(\"encode payload: %w\", err)\n}","handlingStrategy":"try-catch","validationCode":"func canEncode(v any) bool { _, err := payloads.EncodeSingle(v); return err == nil }","typeGuard":null,"tryCatchPattern":"defer func() {\n\tif r := recover(); r != nil {\n\t\tlogger.Error(\"MustEncodeSingle panicked\", r)\n\t\terr = fmt.Errorf(\"payload encode failed: %v\", r)\n\t}\n}() // wrap the call site that uses MustEncodeSingle","preventionTips":["Prefer EncodeSingle over MustEncodeSingle outside tests","Verify encoded values are supported by the configured data converter (no nil/channels/functions)","Register custom converters for application-specific types","Keep Must* helpers confined to test code and known-safe constant values"],"tags":["go","payloads","encoding","panic"],"backgroundTag":"payload-encoding-failed","analyzedSha":"bde624efd13fbd3843654058db6d9c716166318b","analyzedAt":"2026-09-01T07:18:39.080Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}