❓ Frequently Asked Questions
No other server uses the same server-id, so why does startup fail with a duplicate ID?
server-id lobby is already in use by another online server; shutting down this server. Set a different server-id in server.yml for each server sharing the database
If you are sure no second server in the synchronization group uses that server-id, then in almost every case this server crashed earlier and its old process was never fully terminated, so it is still running in the background.
At startup the plugin sends a probe addressed to that ID and waits 3 seconds: when nothing answers, the leftover identity is taken over; as soon as a process answers, it is treated as a conflict and the server shuts down. Answering probes and renewing the heartbeat never run on the Minecraft main thread, so a server whose main thread is already stuck and whose console has stopped scrolling, one that looks crashed to you, keeps answering for as long as the JVM process is alive.
A new ID does let the server start, but it joins the synchronization group under a brand new identity, session locks left over from the previous run do not move with it, and that tends to cause worse data problems. Check for the leftover process first.
1. Check whether the old process is still running
The heartbeat is renewed every 3 seconds and lives for 9 seconds. Query the remaining time a few times in a row: if it keeps jumping back to around 9000, a process really is renewing it in the background; -2 means the key does not exist, so skip to the last section. The database index comes from the /0 at the end of redis.url in config.yml:
redis-cli -n 0 PTTL sparrow-sync:server:lobby
Then find the extra process with ps -ef | grep java (jps -l on Windows).
During shutdown Minecraft disables plugins first, then releases the listening port, and only afterwards saves worlds and waits for the chunk system and I/O thread pools to finish. If that tail hangs, the process keeps running long after the port is free. Closing a screen or tmux window, or the terminal, does not necessarily end the JVM either.
2. Terminate the leftover process and restart
Use kill <PID> first to give it one chance to shut down properly, then check again after about 30 seconds. If the process is still there and the server log has produced no new output for a long time, force it with kill -9 <PID> (taskkill /PID <PID> /F on Windows) — note that forcing it gives the server no chance to save worlds and player data.
Once the process is gone the heartbeat key expires on its own within 9 seconds, so wait fifteen seconds or so before starting the server. On a successful takeover the plugin writes a record to its log directory (plugins/SparrowSync/logs/ by default) noting that the leftover identity was taken over.
Still failing after you confirmed there is no leftover process
Then there really is a duplicate in the configuration. Check plugins/SparrowSync/server.yml on every server in the synchronization group and make sure no two of them share a server-id. The most common cause is copying a whole server directory and forgetting to change it.
How do I move data to another database?
If you want to change the database Sparrow Sync uses, export your data with dump_all, switch the storage configuration, then import the archive with import_all. This also works when switching storage types, such as moving from MySQL to PostgreSQL.
Enable the whitelist on all servers in the synchronization group and have online players log out before exporting. A whitelist does not disconnect players who are already online. Keep player access restricted until migration is complete so new saves do not leave the exported data out of date.
1. Export from the current database
Keep the current database configuration in place. Choose one server connected to it and run this command in its console:
/sparrow-sync data dump_all database-migration.zip
Wait for the console to confirm that the export completed. The archive is saved to plugins/SparrowSync/snapshot/dump/database-migration.zip. Keep a copy of it before proceeding.
2. Switch to the new database
Stop the servers in the synchronization group. Update the persistent storage type and connection settings in config.yml to point to the new database. See Installing the Plugin for database configuration details.
Make the same change on every server in the group: they should all use the new database and matching table or collection prefixes, while keeping their individual server-id values.
3. Import into the new database
Start one server with the new configuration, keeping the whitelist enabled, and check that the database connection succeeds. Place the exported ZIP in that server's plugins/SparrowSync/snapshot/dump/ directory, then run:
/sparrow-sync data import_all database-migration.zip
Wait for the import result in the console. Import the archive once into the shared database; each server does not need its own import.
4. Verify the data and reopen the servers
After a successful import, check player snapshot lists and log in with a test account to verify that data loads correctly. Once everything looks right, start the remaining servers with the new configuration and lift the access restrictions.
Keep the original database and exported ZIP until you have finished checking the migration. If the import reports failures, keep access restricted and investigate the console errors first.