{"record":{"id":"c17c0d15afb19b79","repo":"XTLS/Xray-core","slug":"unsupported-router-implementation","errorCode":null,"errorMessage":"unsupported router implementation","messagePattern":"unsupported router implementation","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"app/router/command/command.go","lineNumber":53,"sourceCode":"\n\tif pt, ok := s.router.(routing.BalancerPrincipleTarget); ok {\n\t\t{\n\t\t\tres, err := pt.GetPrincipleTarget(request.GetTag())\n\t\t\tif err != nil {\n\t\t\t\terrors.LogInfoInner(ctx, err, \"unable to obtain principle target\")\n\t\t\t} else {\n\t\t\t\tret.Balancer.PrincipleTarget = &PrincipleTargetInfo{Tag: res}\n\t\t\t}\n\t\t}\n\t}\n\treturn &ret, nil\n}\n\nfunc (s *routingServer) OverrideBalancerTarget(ctx context.Context, request *OverrideBalancerTargetRequest) (*OverrideBalancerTargetResponse, error) {\n\tif bo, ok := s.router.(routing.BalancerOverrider); ok {\n\t\treturn &OverrideBalancerTargetResponse{}, bo.SetOverrideTarget(request.BalancerTag, request.Target)\n\t}\n\treturn nil, errors.New(\"unsupported router implementation\")\n}\n\nfunc (s *routingServer) AddRule(ctx context.Context, request *AddRuleRequest) (*AddRuleResponse, error) {\n\tif bo, ok := s.router.(routing.Router); ok {\n\t\treturn &AddRuleResponse{}, bo.AddRule(request.Config, request.ShouldAppend)\n\t}\n\treturn nil, errors.New(\"unsupported router implementation\")\n}\n\nfunc (s *routingServer) RemoveRule(ctx context.Context, request *RemoveRuleRequest) (*RemoveRuleResponse, error) {\n\tif bo, ok := s.router.(routing.Router); ok {\n\t\treturn &RemoveRuleResponse{}, bo.RemoveRule(request.RuleTag)\n\t}\n\treturn nil, errors.New(\"unsupported router implementation\")\n}\n\nfunc (s *routingServer) ListRule(ctx context.Context, request *ListRuleRequest) (*ListRuleResponse, error) {\n\tif bo, ok := s.router.(routing.Router); ok {","sourceCodeStart":35,"sourceCodeEnd":71,"githubUrl":"https://github.com/XTLS/Xray-core/blob/7d214f8b094f75322fa3990f8aadad1c912f24f5/app/router/command/command.go#L35-L71","documentation":"The gRPC OverrideBalancerTarget handler type-asserts the registered router to routing.BalancerOverrider. Only the real app/router Router (or a custom implementation providing SetOverrideTarget/GetOverrideTarget/GetPrincipleTarget) satisfies it; anything else gets this error. It signals an environment/wiring problem, not a user-input problem.","triggerScenarios":"RoutingService server constructed with a router implementation lacking the BalancerOverrider interface (mocks in tests, alternative router packages, older Router version).","commonSituations":"Unit tests injecting a fake router; forks that replaced the router; version mismatch where the command package is newer than the router implementation.","solutions":["Register the standard app/router instance as the handler for routing.RoutingService","If using a custom router, implement SetOverrideTarget/GetOverrideTarget/GetPrincipleTarget on it","Align versions of xray-core packages so command and router come from the same release"],"exampleFix":"// before\ncommand.NewRoutingServer(mockRouter, nil) // mock lacks BalancerOverrider\n\n// after\ncommand.NewRoutingServer(realRouter, routingStats) // app/router.Router implements it","handlingStrategy":"type-guard","validationCode":null,"typeGuard":"func supportsOverride(r interface{}) bool {\n    _, ok := r.(routing.BalancerOverrider)\n    return ok\n}","tryCatchPattern":null,"preventionTips":["Wire command services against the real app/router instance in production","Add compile-time assertion: var _ routing.BalancerOverrider = (*router.Router)(nil)","Run integration tests that exercise the gRPC surface, not just unit tests with mocks"],"tags":["routing","grpc","type-assertion","api"],"backgroundTag":null,"analyzedSha":"7d214f8b094f75322fa3990f8aadad1c912f24f5","analyzedAt":"2026-08-15T14:26:24.325Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}