{"record":{"id":"313ebccb4ba8d422","repo":"XTLS/Xray-core","slug":"unknown-operation","errorCode":null,"errorMessage":"unknown operation","messagePattern":"unknown operation","errorType":"exception","errorClass":"errors.Error","httpStatus":null,"severity":"error","filePath":"app/proxyman/command/command.go","lineNumber":88,"sourceCode":"\tohm outbound.Manager\n}\n\nfunc (s *handlerServer) AddInbound(ctx context.Context, request *AddInboundRequest) (*AddInboundResponse, error) {\n\tif err := core.AddInboundHandler(s.s, request.Inbound); err != nil {\n\t\treturn nil, err\n\t}\n\n\treturn &AddInboundResponse{}, nil\n}\n\nfunc (s *handlerServer) RemoveInbound(ctx context.Context, request *RemoveInboundRequest) (*RemoveInboundResponse, error) {\n\treturn &RemoveInboundResponse{}, s.ihm.RemoveHandler(ctx, request.Tag)\n}\n\nfunc (s *handlerServer) AlterInbound(ctx context.Context, request *AlterInboundRequest) (*AlterInboundResponse, error) {\n\trawOperation, err := request.Operation.GetInstance()\n\tif err != nil {\n\t\treturn nil, errors.New(\"unknown operation\").Base(err)\n\t}\n\toperation, ok := rawOperation.(InboundOperation)\n\tif !ok {\n\t\treturn nil, errors.New(\"not an inbound operation\")\n\t}\n\n\thandler, err := s.ihm.GetHandler(ctx, request.Tag)\n\tif err != nil {\n\t\treturn nil, errors.New(\"failed to get handler: \", request.Tag).Base(err)\n\t}\n\n\treturn &AlterInboundResponse{}, operation.ApplyInbound(ctx, handler)\n}\n\nfunc (s *handlerServer) ListInbounds(ctx context.Context, request *ListInboundsRequest) (*ListInboundsResponse, error) {\n\thandlers := s.ihm.ListHandlers(ctx)\n\tresponse := &ListInboundsResponse{}\n\tif request.GetIsOnlyTags() {","sourceCodeStart":70,"sourceCodeEnd":106,"githubUrl":"https://github.com/XTLS/Xray-core/blob/7d214f8b094f75322fa3990f8aadad1c912f24f5/app/proxyman/command/command.go#L70-L106","documentation":"Returned by handlerServer.AlterInbound (app/proxyman/command/command.go:88) when request.Operation.GetInstance() fails: the serialized Any operation message could not be turned into a concrete operation. Xray looks the operation type up in the global proto type registry; an unregistered or unknown type_url fails here.","triggerScenarios":"Sending an AlterInboundRequest whose Operation Any carries a type_url that was never registered (custom operation types not compiled into the binary), or a payload that fails to unmarshal. Also occurs with version mismatch: a newer client sending an operation type the older server build does not know.","commonSituations":"API clients built against different xray-core versions than the server; protobuf Any fields constructed by hand with the wrong type URL string (must match the registered proto name exactly).","solutions":["Use serial.ToTypedMessage (Go) or the exact registered type URL when constructing the operation Any.","Match client and server xray-core versions so all operation types exist on the server.","Prefer the typed helpers (AddUserOperation/RemoveUserOperation) instead of hand-built Any payloads.","Read the Base error to distinguish 'unknown type' from 'unmarshal failed'."],"exampleFix":"// before\nop := &anypb.Any{TypeUrl: \"xray.app.proxyman.command.AddUserOperation\", Value: arbitrary}\n\n// after\naddOp := &command.AddUserOperation{User: user}\nop := serial.ToTypedMessage(addOp)","handlingStrategy":"validation","validationCode":"// confirm the operation type is registered before sending\nif serial.MessageType((*command.AddUserOperation)(nil)) == \"\" {\n    return errors.New(\"AddUserOperation not registered in this build\")\n}","typeGuard":null,"tryCatchPattern":"resp, err := client.AlterInbound(ctx, req)\nif err != nil && strings.Contains(err.Error(), \"unknown operation\") {\n    return fmt.Errorf(\"server build lacks this operation; upgrade server: %w\", err)\n}","preventionTips":["Build operation Any messages with typed helpers (serial.ToTypedMessage), never raw bytes.","Pin matching xray-core versions on API client and server."],"tags":["go","xray","api","protobuf","versioning"],"backgroundTag":null,"analyzedSha":"7d214f8b094f75322fa3990f8aadad1c912f24f5","analyzedAt":"2026-08-15T14:26:24.325Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}