›

Stepped upgrade

When the in-dashboard updater tells you to run a shell command instead of doing it automatically.

Why you're seeing this

SparkBox's one-click self-updater supports jumping most versions in place. But some old versions need a migration to run first — a database schema change, a new signing key, or a file layout move. If you're too many versions behind, the updater returns a stepped_upgrade response instead of running an update it can't safely sequence on its own.

This isn't a bug. It's the updater refusing to do something it can't guarantee will work cleanly. Your current install keeps running exactly as it was — nothing has changed.

The fix — one command

Open an SSH session to your NAS or VPS and run:

curl -fsSL https://get.tomsparkbox.com/install.sh | sudo bash

That's the same installer that set SparkBox up originally. When run against an existing install, it upgrades in place — pulling the latest release, preserving your .env, state, backups, and module data. It also applies whichever intermediate migrations the in-dashboard updater wanted to skip.

Typical runtime: ~60 seconds on a NAS, faster on a VPS. The dashboard goes offline briefly while containers recreate and comes back on the new version.

How to know when it's done

The command prints a green [OK] SparkBox is running! at the end. After that, refresh your browser at http://<your-host>:8443/ and the dashboard will show the new version in the bottom-left footer.

What if the upgrade fails?

The installer writes a rollback copy of your previous install at /opt/sparkbox.rollback-<timestamp>/ before swapping the new version in. If the new dashboard fails to come healthy within 180 seconds, SparkBox automatically rolls back to your previous version — you won't lose data or end up on a broken release.

If auto-rollback itself fails, the rollback directory is still on disk. Ask Tom's AI assistant on d/sparkbox with the output of sudo /opt/sparkbox/sparkbox doctor and we'll help you recover.

How to avoid this next time

Keep auto-update enabled (Updates → Auto-Update Schedule → Enable scheduled updates) so you never drift more than one release behind. Each in-place upgrade is small. Falling 20 releases behind is what triggers stepped-upgrade mode.