{"record":{"id":"26ce6b19d7b3c1b3","repo":"henrygd/beszel","slug":"failed-to-unmarshal-generic-response-data-w","errorCode":null,"errorMessage":"failed to unmarshal generic response data: %w","messagePattern":"failed to unmarshal generic response data: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/hub/transport/transport.go","lineNumber":39,"sourceCode":"\t// The dest parameter should be a pointer to the expected response type.\n\tRequest(ctx context.Context, action common.WebSocketAction, req any, dest any) error\n\t// IsConnected returns true if the transport connection is active.\n\tIsConnected() bool\n\t// Close terminates the transport connection.\n\tClose()\n}\n\n// UnmarshalResponse unmarshals an AgentResponse into the destination type.\n// It first checks the generic Data field (0.19+ agents), then falls back\n// to legacy typed fields for backward compatibility with 0.18.0 agents.\nfunc UnmarshalResponse(resp common.AgentResponse, action common.WebSocketAction, dest any) error {\n\tif dest == nil {\n\t\treturn errors.New(\"nil destination\")\n\t}\n\t// Try generic Data field first (0.19+)\n\tif len(resp.Data) > 0 {\n\t\tif err := cbor.Unmarshal(resp.Data, dest); err != nil {\n\t\t\treturn fmt.Errorf(\"failed to unmarshal generic response data: %w\", err)\n\t\t}\n\t\treturn nil\n\t}\n\t// Fall back to legacy typed fields for older agents/hubs.\n\treturn unmarshalLegacyResponse(resp, action, dest)\n}\n\n// unmarshalLegacyResponse handles legacy responses that use typed fields.\nfunc unmarshalLegacyResponse(resp common.AgentResponse, action common.WebSocketAction, dest any) error {\n\tswitch action {\n\tcase common.GetData:\n\t\td, ok := dest.(*system.CombinedData)\n\t\tif !ok {\n\t\t\treturn fmt.Errorf(\"unexpected dest type for GetData: %T\", dest)\n\t\t}\n\t\tif resp.SystemData == nil {\n\t\t\treturn errors.New(\"no system data in response\")\n\t\t}","sourceCodeStart":21,"sourceCodeEnd":57,"githubUrl":"https://github.com/henrygd/beszel/blob/b38fb7dafa60812cc22e6a84ce313e94f1ce0a32/internal/hub/transport/transport.go#L21-L57","documentation":"UnmarshalResponse (internal/hub/transport/transport.go:39) first tries the generic Data field used by 0.19+ agents. If resp.Data is non-empty but cbor.Unmarshal(resp.Data, dest) fails, it returns 'failed to unmarshal generic response data'. This means the payload was received but its shape/type does not match the caller's destination type.","triggerScenarios":"Agent/hub version skew: a 0.19+ agent returns Data whose shape differs from what the hub's dest expects; the action's payload type changed between releases; dest is a pointer to the wrong struct for the requested action.","commonSituations":"Upgrading hub without upgrading agent (or vice versa); custom actions returning changed schemas; passing a mismatched dest pointer (e.g. *string for a GetData call).","solutions":["Align hub and agent versions (upgrade both to the same release)","Verify dest matches the documented response type for the action","Read the wrapped cbor error to identify the exact field/type mismatch","If the agent is legacy (0.18.x) with empty Data, ensure fallback path applies — check why Data is non-empty but malformed"],"exampleFix":"// before\nvar data string\nerr := transport.Request(ctx, common.GetData, nil, &data) // wrong dest type\n// after\nvar data system.CombinedData\nerr := transport.Request(ctx, common.GetData, nil, &data)","handlingStrategy":"validation","validationCode":"var probe system.CombinedData\nif err := cbor.Unmarshal(resp.Data, &probe); err != nil {\n    return fmt.Errorf(\"agent payload incompatible with hub schema: %w\", err)\n}","typeGuard":"func isVersionCompatible(hubVer, agentVer string) bool {\n    hv, av := semver.Parse(hubVer), semver.Parse(agentVer)\n    return av.Major == hv.Major && av.Minor >= 19 // generic Data field era\n}","tryCatchPattern":"err := t.Request(ctx, action, req, dest)\nif err != nil && strings.Contains(err.Error(), \"failed to unmarshal generic response data\") {\n    return fmt.Errorf(\"hub/agent version mismatch on %s: %w\", action, err)\n}","preventionTips":["Upgrade hub and agent in lockstep","Match dest types to the documented response schema for each action","Test requests against both current and one-version-old agents","Log the wrapped cbor error to pinpoint field mismatches"],"tags":["cbor","schema-mismatch","versioning"],"backgroundTag":"response-decode-failed","analyzedSha":"b38fb7dafa60812cc22e6a84ce313e94f1ce0a32","analyzedAt":"2026-08-31T15:10:10.149Z","schemaVersion":2},"datasetVersion":"2026-08-31T19:17:28.585Z"}