Upgrade checkpoints
A checkpoint is a release that your instance must install and start successfully before it can move to any later release. Upgrading past a checkpoint without completing it can leave data in a state that later releases cannot repair.
Appsmith marks a release as a checkpoint when a change needs time to complete on a running instance. The checkpoint blocks further upgrades until that work is done, or until an administrator chooses to skip it.
Checkpoints apply only to self-hosted instances. Appsmith Cloud does not use them.
Each checkpoint belongs to a release line. Installing the checkpoint version, or any later patch release on the same line, counts as reaching the checkpoint. Appsmith blocks upgrades to the next release line until the checkpoint is complete.
While you are on the checkpoint release
Sign in as an instance administrator, open Admin Settings, and under Instance, select Admin central.
When a checkpoint still needs attention, Admin central lists it and explains its purpose. Stay on this release until the checkpoint is complete, and then upgrade. Each checkpoint has a Learn more link to details specific to that release.
When the work the checkpoint describes is done, confirm the checkpoint. Alternatively, you can skip it. Skipping records that you chose to move on, and later upgrades do not prompt you about that checkpoint again. Before you skip, read the confirmation message on the page, which describes the work that will remain unfinished.
If the server does not start
The server fails to start when the instance was upgraded past a checkpoint that was never completed. Appsmith stops the backend before it finishes starting, so Admin central is not available.
Open the backend logs and look for the following message:
APPSMITH BACKEND START ABORTED — CHECKPOINT MISSED
The log states that a mandatory checkpoint was missed, names the version you must install before you continue, and includes instructions specific to that checkpoint. If later checkpoints were also missed, the log lists them in order. Complete the first missed checkpoint before the others.
Get the instance running again
- Note the version that the log tells you to return to.
- Install that version by following the same steps as any other upgrade in Upgrade Appsmith versions. Pin the image to that exact version. Do not upgrade directly to the release you were originally trying to reach.
- Wait for the instance to start.
- Sign in as an instance administrator and complete the checkpoint in Admin central.
- Upgrade again. If the log listed later checkpoints, repeat these steps for each one, in the order listed.
If you cannot use Admin central
If you are certain the checkpoint does not apply to your instance, but you cannot confirm that in Admin central because the server does not start, use the environment variable shown in the log:
APPSMITH_CHECKPOINT_OVERRIDE="<version>"
Set the variable to the version named in the log, including the leading v, and restart the instance. Appsmith records the checkpoint as skipped and continues starting. After the instance is running, remove the variable so that the override does not remain in effect on later restarts.
If the value does not match the checkpoint that is blocking startup, Appsmith ignores it and the backend still does not start. Check the log again and use the version it names.
Skipping a checkpoint this way has the same effect as skipping it in Admin central.
After a checkpoint is complete
Admin central keeps a record of completed checkpoints, including the version, the name, how the checkpoint was completed, who completed it, and when. A checkpoint is considered complete when an administrator confirms it, when it is skipped, when Appsmith completes the check automatically, or when it does not apply to the instance.
When nothing needs attention, Admin central shows There is no action required for this instance.