{"record":{"id":"b74ff85eae9dffcb","repo":"kopia/kopia","slug":"missing-initialization-request","errorCode":null,"errorMessage":"missing initialization request","messagePattern":"missing initialization request","errorType":"http","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/server/grpc_session.go","lineNumber":628,"sourceCode":"\nfunc makeEntryMetadata(em *manifest.EntryMetadata) *grpcapi.ManifestEntryMetadata {\n\treturn &grpcapi.ManifestEntryMetadata{\n\t\tId:           string(em.ID),\n\t\tLength:       int32(em.Length), //nolint:gosec\n\t\tModTimeNanos: em.ModTime.UnixNano(),\n\t\tLabels:       em.Labels,\n\t}\n}\n\nfunc (s *Server) handleInitialSessionHandshake(srv grpcapi.KopiaRepository_SessionServer, dr repo.DirectRepository) (repo.WriteSessionOptions, error) {\n\tinitializeReq, err := srv.Recv()\n\tif err != nil {\n\t\treturn repo.WriteSessionOptions{}, errors.Wrap(err, \"unable to read initialization request\")\n\t}\n\n\tir := initializeReq.GetInitializeSession()\n\tif ir == nil {\n\t\treturn repo.WriteSessionOptions{}, errors.New(\"missing initialization request\")\n\t}\n\n\tscc := dr.ContentReader().SupportsContentCompression()\n\n\tif err := s.send(srv, initializeReq.GetRequestId(), &grpcapi.SessionResponse{\n\t\tResponse: &grpcapi.SessionResponse_InitializeSession{\n\t\t\tInitializeSession: &grpcapi.InitializeSessionResponse{\n\t\t\t\tParameters: &grpcapi.RepositoryParameters{\n\t\t\t\t\tHashFunction:               dr.ContentReader().ContentFormat().GetHashFunction(),\n\t\t\t\t\tHmacSecret:                 dr.ContentReader().ContentFormat().GetHmacSecret(),\n\t\t\t\t\tSplitter:                   dr.ObjectFormat().Splitter,\n\t\t\t\t\tSupportsContentCompression: scc,\n\t\t\t\t},\n\t\t\t},\n\t\t},\n\t}); err != nil {\n\t\treturn repo.WriteSessionOptions{}, errors.Wrap(err, \"unable to send response\")\n\t}","sourceCodeStart":610,"sourceCodeEnd":646,"githubUrl":"https://github.com/kopia/kopia/blob/82495e54b584c1ef6073c9e1be048f57f8aef078/internal/server/grpc_session.go#L610-L646","documentation":"During the initial gRPC session handshake, the server reads an initialization request from the client and expects a non-nil InitializeSession payload. If initializeReq.GetInitializeSession() is nil — meaning the client sent a request of a different type or an empty request — the handshake is aborted with this error and no session is created.","triggerScenarios":"A gRPC client calls the session initialization RPC (handled by handleInitialSessionHandshake in internal/server/grpc_session.go) with a grpcapi.Request that has no InitializeSession oneof member set, or sends an empty/uninitialized request message.","commonSituations":"Version mismatch between client and server where the client sends a different handshake message type; a buggy or hand-rolled client that forgets to populate the InitializeSession field; a proxy/middleware that strips or rewrites the request payload.","solutions":["Fix the client to populate the SessionResponse/Request oneof with InitializeSession before sending the initial handshake.","Verify client and server kopia versions are compatible (same grpcapi protocol).","Check that no intermediate proxy is altering or dropping the request payload.","Capture the gRPC traffic (grpclog) to confirm what the client actually sent."],"exampleFix":"// before: sending an empty request\nreq := &grpcapi.Request{RequestId: id}\n// after\nreq := &grpcapi.Request{RequestId: id, Request: &grpcapi.Request_InitializeSession{InitializeSession: &grpcapi.InitializeSession{}}}","handlingStrategy":"try-catch","validationCode":"// client side: before sending\nif req.GetInitializeSession() == nil {\n    return errors.New(\"refusing to send handshake without InitializeSession payload\")\n}","typeGuard":"if ir := initializeReq.GetInitializeSession(); ir == nil { /* abort: wrong request type */ }","tryCatchPattern":"if err := session.Connect(ctx); err != nil {\n    if strings.Contains(err.Error(), \"missing initialization request\") {\n        // fix client protocol payload / upgrade client\n    }\n}","preventionTips":["Always populate the InitializeSession oneof in the initial gRPC request.","Keep client and server on matching kopia versions.","Add protocol-level integration tests for the handshake."],"tags":["grpc","handshake","protocol","session"],"backgroundTag":"unexpected-api-response-shape","analyzedSha":"82495e54b584c1ef6073c9e1be048f57f8aef078","analyzedAt":"2026-09-07T20:35:21.689Z","contentChangedAt":"2026-09-07T20:35:21.689Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}