Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Databases and Redis

MySQL replica will not start: could not initialize master info structure

ErrorCould not initialize connection metadata structure; more error messages can be found in the MySQL error log

Short answer

Error 1201 means the replica could not load its saved replication state, the connection metadata and relay log records. The usual causes are relay log file names that no longer match after a host name change, or stale metadata from an earlier setup. Read the MySQL error log first, then fix the relay log names or run RESET REPLICA ALL and configure the source again.

  • Applies to MySQL 8.0.22+, MySQL 8.4
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    The 1201 message is only a wrapper. The line that explains it is in the server error log, written at the moment you ran START REPLICA. Find the path and read the last lines.

    SHOW VARIABLES LIKE 'log_error';
    SHOW VARIABLES LIKE 'relay_log%';
  2. 2Match what you see, then jump to its fix

    1. 1Failed to open the relay log, or Could not find target log during relay log initialization, in the error logThe replica's host name changed, so the relay log names no longer matchFix
    2. 2The error log shows no host-name problem, and the server was a replica before, or was restored from a copy that carried replication stateStale replication metadata and relay logs from an earlier setupFix

What does the error look like?

  • Could not initialize connection metadata structure; more error messages can be found in the MySQL error log
  • Failed to open the relay log
  • Could not find target log during relay log initialization

Cause 1 of 2

The replica's host name changed, so the relay log names no longer match

1Check

By default relay logs are named after the host, in the form host_name-relay-bin.nnnnnn. If the machine was renamed (or cloned from a snapshot with another name) after replication was set up, the index file still lists the old names. Compare the files on disk with the current host name.

hostname
ls /var/lib/mysql | grep relay-bin

2Fix

Stop mysqld, then put the contents of the old relay log index file in front of the new one and use it as the index, as the MySQL manual describes. Start the server again. To stop this from happening twice, set relay_log and relay_log_index to fixed names in my.cnf.

# my.cnf, under [mysqld]
relay_log       = /var/lib/mysql/replica-relay-bin
relay_log_index = /var/lib/mysql/replica-relay-bin.index

# with mysqld stopped, merge the index files
cat new_relay_log_name.index >> old_relay_log_name.index
mv old_relay_log_name.index new_relay_log_name.index

3Verify

Start the server, start replication and check that both threads say Yes.

START REPLICA;
SHOW REPLICA STATUS\G

Confirmed by dev.mysql.com

Did this fix it?

Cause 2 of 2

Stale replication metadata and relay logs from an earlier setup

1Check

The connection settings and the SQL thread position live in the tables mysql.slave_master_info and mysql.slave_relay_log_info. A copy of the data directory or a restore can bring these tables along with positions that do not match the relay log files that exist.

SELECT Host, Port, User_name FROM mysql.slave_master_info;
SELECT Relay_log_name, Relay_log_pos FROM mysql.slave_relay_log_info;

2Fix

Stop the threads and clear the replication metadata completely, then give the replica its connection settings again with the file name and position (or GTID auto-positioning) of the source. Do not edit the two tables by hand; the manual says that is not supported.

STOP REPLICA;
RESET REPLICA ALL;
CHANGE REPLICATION SOURCE TO
  SOURCE_HOST='source.example.com',
  SOURCE_USER='repl',
  SOURCE_PASSWORD='replace-me',
  SOURCE_LOG_FILE='binlog.000145',
  SOURCE_LOG_POS=235;
START REPLICA;

3Verify

Both threads should report Yes and the lag should start to fall.

SHOW REPLICA STATUS\G

Confirmed by dev.mysql.com

Did this fix it?

How do I stop it coming back?

  • Set relay_log and relay_log_index explicitly in my.cnf when you build a replica, so a new host name cannot break them.
  • Include mysql.slave_master_info and mysql.slave_relay_log_info in backups of a replica, as the manual advises.
  • Never edit the replication metadata tables by hand.
  • Keep a note of the source binary log file and position taken when the replica was seeded.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.