{"record":{"id":"b025e4fb268f0c58","repo":"XTLS/Xray-core","slug":"failed-to-get-handler","errorCode":null,"errorMessage":"failed to get handler: ","messagePattern":"failed to get handler: ","errorType":"exception","errorClass":"errors.Error","httpStatus":null,"severity":"error","filePath":"app/proxyman/command/command.go","lineNumber":97,"sourceCode":"}\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() {\n\t\tfor _, handler := range handlers {\n\t\t\tresponse.Inbounds = append(response.Inbounds, &core.InboundHandlerConfig{\n\t\t\t\tTag: handler.Tag(),\n\t\t\t})\n\t\t}\n\t} else {\n\t\tfor _, handler := range handlers {\n\t\t\tresponse.Inbounds = append(response.Inbounds, &core.InboundHandlerConfig{\n\t\t\t\tTag:              handler.Tag(),","sourceCodeStart":79,"sourceCodeEnd":115,"githubUrl":"https://github.com/XTLS/Xray-core/blob/7d214f8b094f75322fa3990f8aadad1c912f24f5/app/proxyman/command/command.go#L79-L115","documentation":"Returned by handlerServer.AlterInbound (app/proxyman/command/command.go:97) when inbound.Manager.GetHandler cannot find a handler registered under request.Tag. The inbound manager keeps handlers keyed by tag; unknown tag means either the inbound was never added, was removed, or the tag string does not match exactly (tags are case-sensitive).","triggerScenarios":"Calling AlterInbound with a tag that does not exist in the running instance: typo, case mismatch, tag of an outbound instead of an inbound, or the inbound was dynamically removed before the call.","commonSituations":"Panel/automation tools reusing stale tags after config reloads; referencing an outbound tag where an inbound tag was meant; whitespace accidentally included in the tag string.","solutions":["List existing inbounds with ListInbounds and copy the exact tag.","Ensure the tag references an inbound, not an outbound.","If inbounds are managed dynamically, re-add the handler before altering it.","Trim whitespace and match case exactly."],"exampleFix":"// before\nreq := &AlterInboundRequest{Tag: \"VLESS-IN\"}\n\n// after — exact tag from config/list\nreq := &AlterInboundRequest{Tag: \"vless-in\"}","handlingStrategy":"validation","validationCode":"// verify the tag exists before altering\nresp, _ := client.ListInbounds(ctx, &command.ListInboundsRequest{})\nknown := map[string]bool{}\nfor _, in := range resp.Inbounds { known[in.Tag] = true }\nif !known[request.Tag] { return fmt.Errorf(\"unknown inbound tag %q\", request.Tag) }","typeGuard":null,"tryCatchPattern":"if err != nil && strings.Contains(err.Error(), \"failed to get handler\") {\n    return fmt.Errorf(\"inbound %q not found; check ListInbounds\", request.Tag)\n}","preventionTips":["Always derive tags from ListInbounds rather than hardcoding.","Tags are case-sensitive; avoid trailing spaces in JSON."],"tags":["go","xray","api","inbound","configuration"],"backgroundTag":null,"analyzedSha":"7d214f8b094f75322fa3990f8aadad1c912f24f5","analyzedAt":"2026-08-15T14:26:24.325Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}