{"record":{"id":"6f296a0fe0bdf31c","repo":"larksuite/cli","slug":"protocol-decode-s-w","errorCode":null,"errorMessage":"protocol decode %s: %w","messagePattern":"protocol decode (.+?): %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/event/adapter/localbus/protocol/codec.go","lineNumber":120,"sourceCode":"\t\tmsg = &Bye{}\n\tcase MsgTypePreShutdownCheck:\n\t\tmsg = &PreShutdownCheck{}\n\tcase MsgTypePreShutdownAck:\n\t\tmsg = &PreShutdownAck{}\n\tcase MsgTypeStatusQuery:\n\t\tmsg = &StatusQuery{}\n\tcase MsgTypeStatusResponse:\n\t\tmsg = &StatusResponse{}\n\tcase MsgTypeShutdown:\n\t\tmsg = &Shutdown{}\n\tcase MsgTypeSourceStatus:\n\t\tmsg = &SourceStatus{}\n\tdefault:\n\t\treturn nil, fmt.Errorf(\"protocol: unknown message type %q\", env.Type)\n\t}\n\n\tif err := json.Unmarshal(line, msg); err != nil {\n\t\treturn nil, fmt.Errorf(\"protocol decode %s: %w\", env.Type, err)\n\t}\n\treturn msg, nil\n}\n","sourceCodeStart":102,"sourceCodeEnd":124,"githubUrl":"https://github.com/larksuite/cli/blob/7fd6ef3c07182257ce776cdc5a614e122d5bd4b3/internal/event/adapter/localbus/protocol/codec.go#L102-L124","documentation":"Decode in internal/event/adapter/localbus/protocol/codec.go wraps a json.Unmarshal failure that occurs while decoding the payload of a recognized localbus envelope message type. The envelope was parsed and its type was known (e.g. SourceStatus), but the JSON body did not match the expected struct. The wrapper preserves the envelope type and the underlying JSON error cause.","triggerScenarios":"Decode() receives a line whose envelope type maps to a concrete struct (e.g. &SourceStatus{}) but json.Unmarshal(line, msg) fails because the body has fields with wrong types (string where number expected), malformed JSON, or null where a struct is required.","commonSituations":"A producer on the bus was built with a different protocol version and serializes fields with changed types; a corrupted or truncated frame on the local transport; a test or custom peer hand-writes frames that do not match the canonical struct encoding.","solutions":["Log the wrapped cause (%w) to see the exact field/type mismatch, then inspect the raw line for the offending field","Verify all bus producers and consumers use the same protocol version / generated structs","Re-encode the frame with this library's Encode so it matches the canonical struct shape","Add a regression test (see TestEncodeDecode*) round-tripping the message to catch drift"],"exampleFix":"// before\nmsg, err := protocol.Decode(line)\nif err != nil { return err } // opaque\n// after\nmsg, err := protocol.Decode(line)\nif err != nil {\n    return fmt.Errorf(\"decode localbus frame: %w\", err) // cause names the bad field\n}","handlingStrategy":"try-catch","validationCode":"if !json.Valid(frame) { return fmt.Errorf(\"frame is not valid JSON\") }","typeGuard":"func isDecodeError(err error) bool { return err != nil && strings.Contains(err.Error(), \"protocol decode \") }","tryCatchPattern":"msg, err := protocol.Decode(line)\nif err != nil {\n    var jsonErr *json.UnmarshalTypeError\n    if errors.As(err, &jsonErr) {\n        log.Printf(\"bad field %s in frame type\", jsonErr.Field)\n    }\n    return fmt.Errorf(\"skip malformed frame: %w\", err)\n}","preventionTips":["Always produce frames via Encode, never hand-written JSON","Pin all bus producers/consumers to the same protocol version","Round-trip test new message types like TestEncodeDecodeEvent","Log the full wrapped error, not just the wrapper text"],"tags":["json","decoding","localbus","protocol"],"backgroundTag":"json-unmarshal-type-mismatch","analyzedSha":"7fd6ef3c07182257ce776cdc5a614e122d5bd4b3","analyzedAt":"2026-09-04T21:17:44.649Z","contentChangedAt":"2026-09-04T21:17:44.649Z","schemaVersion":2},"datasetVersion":"2026-09-12T02:17:10.037Z"}