| Stale replica readsApplication writes a row and immediately reads back old state | readwritesplit sends the subsequent SELECT to an asynchronous replica before the primary's GTID event has finished applying there. | Configure causal_reads=local (or fast) with causal_reads_timeout=2s in the readwritesplit service so MaxScale waits for the client's last written GTID on the replica or falls back to the primary. |
|---|
| Session variable pinning95% of SELECT queries still hit the primary instead of replicas | ORM connection initialization runs SET autocommit, SET sql_mode, or creates temporary tables, which pins the connection to the primary if max_sescmd_history is exceeded. | Inspect maxctrl show sessions, enable connection_keepalive, tune max_sescmd_history, and strip unnecessary session-pinning statements from application startup. |
|---|
| Dual-monitor split-brainTwo MaxScale instances promote different replicas during a network blip | Active-active MaxScale nodes run mariadbmon with auto_failover=true but without cooperative_monitoring_locks enabled. | Set cooperative_monitoring_locks=majority_of_all in mariadbmon so only the MaxScale instance holding the majority backend lock executes failover. |
|---|
| Mid-flight errors on switchoverPlanned maintenance switchovers throw broken pipe errors in the app | Connections are terminated abruptly when the primary enters maintenance mode without draining transactions or replaying in-flight queries. | Enable master_reconnection=true and transaction_replay=true, and use maxctrl set server <node> maintenance to drain open transactions cleanly before switchover. |
|---|
| Single MaxScale SPOFThe database cluster has 3 nodes, but a single MaxScale VM is a SPOF | Applications point to one MaxScale IP address; if that proxy VM reboots, the entire 3-node Galera or GTID cluster becomes unreachable. | Deploy two redundant MaxScale nodes across availability zones fronted by a Keepalived VRRP floating VIP or cloud Network Load Balancer, or run MaxScale as an app-local sidecar. |
|---|
| MaxScale 25.01 upgrade blockPackage repo upgrade fails or introduces Enterprise subscription terms | MaxScale 25.01+ changed production licensing terms in January 2025, requiring teams on Community Server to review their proxy strategy. | Audit your current MaxScale version, evaluate MariaDB Enterprise Server subscription value vs BSL conversion dates, or design an equivalent ProxySQL + Orchestrator stack. |
|---|