{"record":{"id":"681dc9abb64aa41a","repo":"temporalio/temporal","slug":"w-cannot-serialize-v","errorCode":null,"errorMessage":"%w: cannot serialize %v","messagePattern":"%w: cannot serialize (.+?)","errorType":"validation","errorClass":"serializer error","httpStatus":null,"severity":"error","filePath":"common/nexus/payload_serializer.go","lineNumber":107,"sourceCode":"\treturn nil\n}\n\nfunc setUnknownNexusContent(nexusHeader nexus.Header, payloadMetadata map[string][]byte) {\n\tfor k, v := range nexusHeader {\n\t\tpayloadMetadata[k] = []byte(v)\n\t}\n\tpayloadMetadata[\"encoding\"] = []byte(\"unknown/nexus-content\")\n}\n\n// Serialize implements nexus.Serializer.\nfunc (payloadSerializer) Serialize(v any) (*nexus.Content, error) {\n\tif v == nil {\n\t\t// Use same structure as the nil serializer from the Nexus Go SDK.\n\t\treturn &nexus.Content{Header: nexus.Header{}}, nil\n\t}\n\tpayload, ok := v.(*commonpb.Payload)\n\tif !ok {\n\t\treturn nil, fmt.Errorf(\"%w: cannot serialize %v\", errSerializer, v)\n\t}\n\n\t// Use the \"nil\" Nexus Content representation for nil Payloads.\n\tif payload == nil {\n\t\t// Use same structure as the nil serializer from the Nexus Go SDK.\n\t\treturn &nexus.Content{Header: nexus.Header{}}, nil\n\t}\n\n\tif len(payload.GetMetadata()) == 0 {\n\t\treturn xTemporalPayload(payload)\n\t}\n\n\tcontent := nexus.Content{Header: nexus.Header{}, Data: payload.Data}\n\tencoding := string(payload.Metadata[\"encoding\"])\n\tmessageType := string(payload.Metadata[\"messageType\"])\n\n\tswitch encoding {\n\tcase \"unknown/nexus-content\":","sourceCodeStart":89,"sourceCodeEnd":125,"githubUrl":"https://github.com/temporalio/temporal/blob/bde624efd13fbd3843654058db6d9c716166318b/common/nexus/payload_serializer.go#L89-L125","documentation":"payloadSerializer.Serialize only accepts *commonpb.Payload (or nil) as the value to serialize into Nexus Content. Any other value type — a raw struct, string, map, etc. — is rejected with this wrapped errSerializer, mirroring the Nexus Go SDK's contract that the Temporal-specific serializer handles Temporal payloads exclusively.","triggerScenarios":"Calling Serialize(v) where v is not *commonpb.Payload — e.g. returning a plain struct or string from a Nexus handler whose server was configured with the Temporal payload serializer.","commonSituations":"Handler signatures using native Go types while the Temporal serializer is registered; test helpers calling Serialize with arbitrary values; refactors that change handler result types without updating serializer configuration.","solutions":["Wrap the value in a *commonpb.Payload (Metadata + Data) before serializing.","Use the default nexus.Serializer if you need to serialize arbitrary Go values.","Align handler signatures with the configured serializer's supported types.","Check the %v in the error message to identify the offending type."],"exampleFix":"// before\ncontent, err := serializer.Serialize(\"hello\") // string not supported\n// after\ncontent, err := serializer.Serialize(&commonpb.Payload{\n    Metadata: map[string][]byte{\"encoding\": []byte(\"json/plain\")},\n    Data:     []byte(`\"hello\"`),\n})","handlingStrategy":"type-guard","validationCode":"func canSerializeWithTemporalSerializer(v any) bool {\n    if v == nil {\n        return true\n    }\n    _, ok := v.(*commonpb.Payload)\n    return ok\n}","typeGuard":"func serializeValue(v any) (*nexus.Content, error) {\n    if p, ok := v.(*commonpb.Payload); ok || v == nil {\n        return payloadSerializer{}.Serialize(p)\n    }\n    return defaultSerializer{}.Serialize(v) // fall back for arbitrary types\n}","tryCatchPattern":"content, err := serializer.Serialize(v)\nif err != nil {\n    return nil, nexus.HandlerErrorf(nexus.HandlerErrorTypeInternal, \"unsupported result type %T\", v)\n}","preventionTips":["Return *commonpb.Payload (or nil) from handlers configured with the Temporal serializer","Keep a compile-time assertion that handler outputs match the serializer contract","Do not mix serializer configurations between environments","Cover each handler's result type in a serialization test"],"tags":["nexus","serialization","type-mismatch","temporal-payload"],"backgroundTag":"serializer-type-mismatch","analyzedSha":"bde624efd13fbd3843654058db6d9c716166318b","analyzedAt":"2026-09-01T07:18:39.080Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}