MySQL replica will not start: could not initialize master info structure
Could not initialize connection metadata structure; more error messages can be found in the MySQL error logShort 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.
Fix it fast
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%';2Match what you see, then jump to its fix
- 1
Failed 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
The 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
- 1
What does the error look like?
Could not initialize connection metadata structure; more error messages can be found in the MySQL error logFailed to open the relay logCould 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-bin2Fix
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.index3Verify
Start the server, start replication and check that both threads say Yes.
START REPLICA;
SHOW REPLICA STATUS\GConfirmed by dev.mysql.com
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\GConfirmed by dev.mysql.com
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:
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- QistLockA NestJS and React SaaS driving an Android Device Owner agent that locks financed phones when payments lapse.
- ShopGoAn e-commerce aggregator with a Python scraping engine behind its catalog, past 10K Google Play downloads.
Related fixes
Databases
Replication stopped: error 1032, coordinator stopped because of worker errors
Can't find record in 'tablename'
Error 1032 on a replica means a change from the source could not be applied because the replica's data no longer matches the source.
3 causes, each with a fixDatabases
Installing the Airflow MySQL provider fails on pkg-config or mysqlclient
Building the mysqlclient wheel fails during the install
The Airflow MySQL provider depends on mysqlclient, which pip compiles against the MySQL C client library.
2 causes, each with a fixDatabases
A query on Aurora MySQL dies with 'table /rdsdbdata/tmp/#sql... is full'
ERROR 1114 (HY000): The table '/rdsdbdata/tmp/#sqlfd_1586_2' is full
In Aurora MySQL 3, internal temporary tables share one pool, and when that pool and the memory-mapped overflow file are used up, a reader instance ends the query with error 1114.
3 causes, each with a fixDatabases
Azure Database for MySQL refuses a connection that does not use SSL
ERROR 3159 (HY000): Connections using insecure transport are prohibited while --require_secure_transport=ON.
Azure Database for MySQL Flexible Server requires encrypted connections by default (require_secure_transport = ON, TLS 1.2).
4 causes, each with a fixDatabases
Compiling a C or C++ program that includes mysql.h fails
undefined reference to `mysql_init'
The compiler only finds mysql.h when the MySQL client development files are installed and their folder is on the include path.
3 causes, each with a fixDatabases
DBeaver fails to resolve Maven dependencies when downloading a database driver
A driver library does not download automatically
DBeaver downloads driver jars from a Maven repository.
3 causes, each with a fix