MySQL replica_allow_higher_version_source: Setup and Best Practices

Cross-version MySQL replication requires strict operational control. When a source server runs on a newer version than its replica, compatibility issues can surface without warning.

• MySQL includes a built-in guardrail for this exact problem: the replica_allow_higher_version_source system variable.
• This parameter lets database administrators choose whether an older replica should accept data streams from a newer source.

Here is a breakdown of how the variable works, how to configure it, and where it fits into your upgrade workflow.

Cross-Version Replication Risks

Take a scenario where an engineer accidentally upgrades a source instance before upgrading the downstream replicas:

Cross-Version Replication Vulnerability Flow

Source Node

Newer Version

Binary Log Stream

Replica Node

Older Version

New Binlog Events

Unrecognized SQL

GTID Header Drift

Engine Inconsistencies

The replica might connect successfully at first. However, newer MySQL versions introduce changes that older binaries cannot handle:

• New Binary Log Events: Updated or unrecognized log structures that older replicas fail to parse.
• SQL Syntax and Functions: New built-in functions, statements, or parser rules that do not exist on the replica.
• Replication Metadata: Structural changes to GTID headers or metadata formats.
• Storage Engine Changes: Internal modifications to InnoDB formats and column data types.

If the source writes an event that the older replica cannot process, the replica's SQL thread halts immediately (ER_SLAVE_FATAL_ERROR), creating replication lag and data divergence.

Earlier, database teams had to rely on custom deployment scripts or manual checks to stop this from happening.

The Role of replica_allow_higher_version_source

The replica_allow_higher_version_source system variable controls whether a replica can connect to a source that runs a higher version of MySQL.

Protocol Handshake Validator

Variable: ON

Source

Version 26.x

I/O

Permissive Pass

Replica

Version 9.x

PASS: I/O thread active. Source handshake accepted without version gate block.

Variable Attributes:

• Default Value: ON
• Scope: GLOBAL
• Dynamic: Yes (updates instantly without a server restart)
• Required Privileges: SYSTEM_VARIABLES_ADMIN plus REPLICATION_SLAVE_ADMIN (or SUPER)

The default setting is ON to keep backward compatibility intact for standard rolling upgrades. However, you can switch it to OFF to strictly block incompatible connections.

How to Configure the Variable

1. Check the Current Value

Run the following query on the replica:

mysql> SHOW VARIABLES LIKE 'replica_allow_higher_version_source';
+-------------------------------------+-------+
| Variable_name                       | Value |
+-------------------------------------+-------+
| replica_allow_higher_version_source | ON    |
+-------------------------------------+-------+
1 row in set (0.003 sec)

2. Set the Variable to OFF at Runtime

To prevent the replica from pulling data from a higher-version source:

mysql> SHOW VARIABLES LIKE 'replica_allow_higher_version_source';
+-------------------------------------+-------+
| Variable_name                       | Value |
+-------------------------------------+-------+
| replica_allow_higher_version_source | ON    |
+-------------------------------------+-------+
1 row in set (0.004 sec)
mysql> SET GLOBAL replica_allow_higher_version_source = OFF;
Query OK, 0 rows affected (0.000 sec)
mysql> SHOW VARIABLES LIKE 'replica_allow_higher_version_source';
+-------------------------------------+-------+
| Variable_name                       | Value |
+-------------------------------------+-------+
| replica_allow_higher_version_source | OFF   |
+-------------------------------------+-------+
1 row in set (0.002 sec)

3. Persist the Value Across Restarts

Write the value to the persistent configuration file:

mysql> SHOW VARIABLES LIKE 'replica_allow_higher_version_source';
+-------------------------------------+-------+
| Variable_name                       | Value |
+-------------------------------------+-------+
| replica_allow_higher_version_source | ON    |
+-------------------------------------+-------+
1 row in set (0.002 sec)
mysql> SET PERSIST replica_allow_higher_version_source = OFF;
Query OK, 0 rows affected (0.002 sec)
mysql> 
mysql> SHOW VARIABLES LIKE 'replica_allow_higher_version_source';
+-------------------------------------+-------+
| Variable_name                       | Value |
+-------------------------------------+-------+
| replica_allow_higher_version_source | OFF   |
+-------------------------------------+-------+
1 row in set (0.002 sec)

With this set to OFF, any script or operator error that points the replica to a higher-version source gets rejected right at the I/O thread layer.

Why MySQL Introduced This Feature

The primary goal is to provide administrators with a mechanism to enforce version compatibility rules. Without such a control, an environment can accidentally end up in an unsupported topology:

In this scenario, the master server was upgraded to MySQL 26.7 while the replica remained on MySQL 9.7.

When version enforcement is active (replica_allow_higher_version_source = OFF), replication halts intentionally at the connection handshake rather than failing silently mid-transaction.

Version Mismatch: Error and Resolution

With replica_allow_higher_version_source = OFF, checking SHOW REPLICA STATUS shows the exact guardrail error:

mysql> show replica status \G
*************************** 1. row ***************************
             Replica_IO_State: 
                  Source_Host: 10.50.58.118
                  Source_User: repl_user
                  Source_Port: 3306
                Connect_Retry: 60
          Read_Source_Log_Pos: 4
               Relay_Log_File: 9184875-mysql-relay-bin.000001
                Relay_Log_Pos: 4
           Replica_IO_Running: No
                   Last_Errno: 0 
                 Skip_Counter: 0
          Exec_Source_Log_Pos: 0
              Relay_Log_Space: 158
              Until_Condition: None
                Until_Log_Pos: 0
           Source_SSL_Allowed: Yes
        Seconds_Behind_Source: 0
Source_SSL_Verify_Server_Cert: No
                Last_IO_Errno: 15671
                Last_IO_Error: Replication from higher version source (26.7.0) to lower version replica (9.7.0) is disallowed due to replica_allow_higher_version_source=OFF.
               Last_SQL_Errno: 0
               Last_SQL_Error: 
  Replicate_Ignore_Server_Ids: 
             Source_Server_Id: 0
                  Source_UUID: 
             Source_Info_File: mysql.slave_master_info
                    SQL_Delay: 0
          SQL_Remaining_Delay: NULL
    Replica_SQL_Running_State: Replica has read all relay log; waiting for more updates
           Source_Retry_Count: 10
                  Source_Bind: 
      Last_IO_Error_Timestamp: 260822 11:50:25
            Executed_Gtid_Set: 3f359584-9df0-11f1-9e86-02010a323a76:1-5
                Auto_Position: 1
1 row in set (0.000 sec)

The error Last_IO_Errno: 15671 stops the I/O thread immediately. Unsupported events never reach the relay logs.

Replication State Monitor

Live Sync Monitor

Setting	I/O Thread	SQL Thread	Last_IO_Errno	Network State
OFF (Enforced)	No	Yes	15671	Connection Terminated
ON (Permissive)	Yes	Yes	0	Continuous Stream

Restoring Replication

If you must allow replication temporarily during a staged maintenance window, enable the variable globally on the replica server to resume the stream:

mysql> SHOW VARIABLES LIKE 'replica_allow_higher_version_source';
+-------------------------------------+-------+
| Variable_name                       | Value |
+-------------------------------------+-------+
| replica_allow_higher_version_source | OFF   |
+-------------------------------------+-------+
1 row in set (0.003 sec)

mysql> 
mysql> set global replica_allow_higher_version_source = 1 ; 
Query OK, 0 rows affected (0.000 sec)

mysql> stop replica ; start replica ;
Query OK, 0 rows affected (0.002 sec)
Query OK, 0 rows affected (0.014 sec)

Verify that both the I/O and SQL threads are active:

mysql> show replica status \G
*************************** 1. row ***************************
             Replica_IO_State: Waiting for source to send event
                  Source_Host: 10.50.58.118
                  Source_User: repl_user
                  Source_Port: 3306
                Connect_Retry: 60
              Source_Log_File: 9216947-mysql-binary.000003
          Read_Source_Log_Pos: 1095
               Relay_Log_File: 9184875-mysql-relay-bin.000002
                Relay_Log_Pos: 455
        Relay_Source_Log_File: 9216947-mysql-binary.000003
           Replica_IO_Running: Yes
          Replica_SQL_Running: Yes
                   Last_Errno: 0
                 Skip_Counter: 0
          Exec_Source_Log_Pos: 1095
              Relay_Log_Space: 701
              Until_Condition: None
               Until_Log_File: 
                Until_Log_Pos: 0
           Source_SSL_Allowed: Yes
        Seconds_Behind_Source: 0
Source_SSL_Verify_Server_Cert: No
                Last_IO_Errno: 0
               Last_SQL_Errno: 0
             Source_Server_Id: 9216947
                  Source_UUID: 3f359584-9df0-11f1-9e86-02010a323a76
             Source_Info_File: mysql.slave_master_info
                    SQL_Delay: 0
          SQL_Remaining_Delay: NULL
    Replica_SQL_Running_State: Replica has read all relay log; waiting for more updates
           Source_Retry_Count: 10
            Executed_Gtid_Set: 3f359584-9df0-11f1-9e86-02010a323a76:1-5
                Auto_Position: 1
1 row in set (0.000 sec)

mysql> 

When to Set the Variable to OFF

Leave the variable at its default (ON) during deliberate rolling upgrades. Turn it OFF under these specific operational conditions:

• Strict Version Governance: Production clusters require absolute binary parity across every node.
• Enforced Upgrade Sequences: Internal SOPs dictate that replicas must always upgrade before the source.
• Compliance Policies: Regulatory frameworks demand pre-approved, uniform database versions.
• Large Topologies: Environments with hundreds of replication channels where misconfigured connections can easily slip past monitoring.
• Automated CI/CD Pipelines: Automated orchestration or failover tools might otherwise attach an un-upgraded node to a new source by mistake.

Cross-Version Replication Best Practices

Follow these production guidelines to avoid replication outages during upgrade cycles:

1. Upgrade Replicas First: Follow the standard MySQL upgrade sequence. Upgrade read replicas to the target version first, verify their stability, and then upgrade or switch traffic to the new source.
2. Maintain Version Parity: Keep source and replica versions matched outside of planned maintenance windows. Read our in-depth article on MySQL replication best practices.
3. Validate in Staging: Test replication across your specific source and target versions using real production query patterns in staging.
4. Use Row-Based Replication: Set binlog_format=ROW to avoid SQL statement parsing failures across version boundaries.
5. Monitor Thread Status: Set up proactive alerts for Last_IO_Errno and replication lag during every upgrade phase.
6. Lock Down Version Controls: Set replica_allow_higher_version_source = OFF on standalone or read-only pools where cross-version replication is banned.

Safe Upgrade Lifecycle Loop

Upgrade Loop

1

Upgrade Replicas

2

Verify GTID Sync

3

Promote Target

4

Lock Guardrails

Summary

The replica_allow_higher_version_source parameter gives database administrators native control over version boundaries. MySQL keeps the setting permissive by default for backward compatibility, but turning it OFF provides a clean, protocol-level safeguard against accidental version drift and broken replication streams.

Plan Your Next MySQL Upgrade with Mydbops

Database upgrades require zero data loss, minimal failover windows, and strict schema validation. The team at Mydbops provides end-to-end MySQL Consulting Services and 24/7 managed support to keep your clusters stable.