Restoring a backup gives you a safe way back to a known-good configuration. If something goes wrong partway through, Buttons automatically returns to what you had before, so a restore attempt can't leave your install half-changed. This page covers restoring a backup, confirming it actually worked, and what to do if it doesn't.
Before you begin#
- A backup file already listed under Settings → Backups → Previous Backups. If you don't have one yet, see Create your first backup.
- A maintenance window: restoring replaces all current configuration and restarts the Buttons server. Everyone connected (operators, other admins, active positions) is disconnected while it restarts.
How a restore works#
When you confirm a restore, Buttons doesn't overwrite your current configuration directly. It builds the restored configuration in a separate, temporary copy first, leaving your current configuration untouched while that happens. Only once that copy is complete does Buttons switch over to it, and at that point, your previous configuration isn't deleted, it's kept as an internal backup rather than being surfaced anywhere in the interface.
If anything fails while building the temporary copy (a corrupt file, an interrupted upload, a version mismatch), Buttons discards the incomplete copy and your original configuration is never touched. There's no manual rollback step to remember; the failure simply leaves you where you started.
This protects you from a failed restore, but not from a successful one you didn't want. If you're not sure the backup you're about to restore is the right one, create a fresh backup of your current configuration first: that's the only way back to it once a restore completes.
Example: rolling back after a bad change#
A configuration change or update didn't go the way you expected, and you want to return to the last known-good state before the change.
- Open Settings → Backups and find the backup you want under Previous Backups for the rule that created it.
- Select the restore icon on that file. The Import backup dialog shows what you're about to restore: Buttons version (with a beta tag if applicable), Exported date, and whether it Includes secrets: confirm this is the backup you meant before continuing.
- Select Import. Buttons prepares the restored configuration, then restarts: the dialog reads "Waiting for server to restart…", then "Server restarting, waiting for it to come back online…". Anyone else connected at the time sees "System is restarting…" and reloads automatically once the server is back.
- When Buttons comes back, work through the verification checklist below before returning the install to service.
Verify the restore before returning to service#
Check that what came back matches what you expected to restore, not just that Buttons is running again:
- Auth → Users: the expected accounts are present, with the roles you expect.
- Connect → Connection: every connection you expect is listed and reaches its normal status (not stuck reconnecting).
- Position: your positions are present with their expected controls, not empty or missing sections.
- Routing: routes and routing rules match what you expected to restore, particularly any that were the reason for the restore.
If the backup was created with secrets excluded, connections that need credentials come back without them: you'll need to re-enter those before the connections can work again.
If you get stuck#
What you see | What to try |
|---|
The restart phase shows "Something went wrong. Please refresh the page manually." | Refresh the page. The restore itself either completed or was rolled back automatically before the failure: the verification checklist above tells you which. |
The Import backup dialog shows an error instead of restarting. | The restore didn't start: your current configuration is untouched. Check the error message for the reason before trying again: a backup made by a newer Buttons version than the one you're restoring into, for example, shows "Configuration file is newer than the current running version of Buttons." |
The restore completed, but something you needed is missing or wrong. | A completed restore isn't reversible from the interface: restore a different backup, or the fresh backup of your prior state if you made one first. |
Where to go next#
