{"record":{"id":"5dc1d58ce8c5dd56","repo":"vitessio/vitess","slug":"unsupported-balancer-mode-s-supported-modes-s","errorCode":null,"errorMessage":"unsupported balancer mode: %s (supported modes: %s)","messagePattern":"unsupported balancer mode: (.+?) \\(supported modes: (.+?)\\)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"go/vt/vtgate/balancer/balancer.go","lineNumber":167,"sourceCode":"//   - See the RFC here: https://github.com/vitessio/vitess/issues/12241\n//   - \"random\": Random balancer that uniformly distributes load without cell affinity\n//   - \"session\": Session balancer that pins a session to the same tablet for the duration of the session. If the tablet goes away, the session is automatically and transparently migrated to another tablet of the same type.\n//\n// Note: \"cell\" mode is handled by the gateway and does not create a balancer instance.\n// operates as a round robin inside of the vtgate's cell\n// Returns an error for unsupported modes.\nfunc NewTabletBalancer(mode Mode, localCell string, vtGateCells []string) (TabletBalancer, error) {\n\tswitch mode {\n\tcase ModePreferCell:\n\t\treturn newFlowBalancer(localCell, vtGateCells), nil\n\tcase ModeRandom:\n\t\treturn newRandomBalancer(localCell, vtGateCells), nil\n\tcase ModeSession:\n\t\treturn newSessionBalancer(localCell), nil\n\tcase ModeCell:\n\t\treturn nil, errors.New(\"cell mode should be handled by the gateway, not the balancer factory\")\n\tdefault:\n\t\treturn nil, fmt.Errorf(\"unsupported balancer mode: %s (supported modes: %s)\", mode, strings.Join(GetAvailableModeNames(), \", \"))\n\t}\n}\n\nfunc newFlowBalancer(localCell string, vtGateCells []string) TabletBalancer {\n\treturn &flowBalancer{\n\t\tlocalCell:   localCell,\n\t\tvtGateCells: vtGateCells,\n\t\tallocations: map[discovery.KeyspaceShardTabletType]*targetAllocation{},\n\t}\n}\n\ntype flowBalancer struct {\n\t//\n\t// Configuration\n\t//\n\n\t// The local cell for the vtgate\n\tlocalCell string","sourceCodeStart":149,"sourceCodeEnd":185,"githubUrl":"https://github.com/vitessio/vitess/blob/01a25a7d176f94613b8d59d799f438380a8760e4/go/vt/vtgate/balancer/balancer.go#L149-L185","documentation":"NewTabletBalancer maps a balancer mode string to a balancer implementation; the default branch rejects unknown mode values listing the supported names. ModeCell is also explicitly rejected here because cell-aware routing is handled by the gateway itself, not the balancer factory.","triggerScenarios":"Configuring vtgate with a --tablet-balancer-mode (or programmatic balancer mode) value that is not one of the defined modes, or explicitly choosing ModeCell which the factory refuses.","commonSituations":"Typo in the balancer mode config value (e.g. 'randomn'); copy of config from an older version using a removed mode name; setting 'cell' expecting the balancer to handle it when the gateway handles cell routing.","solutions":["Set the mode to one of the supported names listed in the error message (e.g. flow, random, session).","Remove the 'cell' mode setting — cell-aware routing is default gateway behavior; use a supported mode or none.","Check the config against the current version's mode list since names may have changed between releases."],"exampleFix":"// before\nbalancerMode = \"cel\"\n// after\nbalancerMode = \"random\" // or flow/session","handlingStrategy":"validation","validationCode":"supported := balancer.GetAvailableModeNames()\nif !slices.Contains(supported, cfg.TabletBalancerMode) {\n    return fmt.Errorf(\"mode %q not supported; use one of %v\", cfg.TabletBalancerMode, supported)\n}","typeGuard":null,"tryCatchPattern":"if _, err := balancer.NewTabletBalancer(mode, cell, cells); err != nil {\n    if strings.Contains(err.Error(), \"unsupported balancer mode\") {\n        log.Warn(\"falling back to default mode\", \"requested\", mode)\n    }\n}","preventionTips":["Validate config against balancer.GetAvailableModeNames() at startup.","Never set mode 'cell' on the balancer; cell routing is gateway-level.","Diff config files against the new version's supported modes when upgrading."],"tags":["vtgate","balancer","config","validation"],"backgroundTag":"invalid-config-value","analyzedSha":"01a25a7d176f94613b8d59d799f438380a8760e4","analyzedAt":"2026-09-01T17:28:30.605Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T15:18:49.778Z"}