Upgrade and Migration Errors | Appsmith

https://docs.appsmith.com/help-and-support/troubleshooting-guide/upgrade-migration-errors • 56 KB fetched
Open original page

Ask AI
Search

Ask Appsmith AI Submit message

Examples How do I install Appsmith using Docker? How do I connect to my local PostgreSQL database? How do I pass inputs from a widget to a query? How do I trigger multiple queries conditionally? How do I fix the error: This value does not evaluate to type Array<Object>?

Try Appsmith

* Get Started

* Introduction

* Build Your First App

* Self Hosting

* New Installation Guides

* Manage Installation

* Upgrade Installation Guides

* Concepts

* Connect Data

* Overview

* How-to Guides

* Reference

* Datasources

* Query Settings

* Concepts

* Build Apps

* Overview

* Quickstart

* How-to Guides

* Reference

* Widgets

* Accessibility

* Theme

* Sample Apps

* Write Code

* Overview

* How-to Guides

* Reference

* Global Objects

* Global Functions

* JS Libraries

* Fetch API

* Data Transformation

* JavaScript Settings

* Concepts

* Best Practices

* Manage Apps and Users

* Authentication

* Granular Access Control

* Versioning with Git

* Setup SCIM Provisioning

* Embed Appsmith

* Migrate Applications

* Audit Logs

* Branding

* External Client Portal

* Packages

* Overview

* Tutorial

* How-to Guides

* Reference

* Package Version Control

* GIT Apps with Packages Best Practices

* Code Packages

* UI Packages

* Workflows

* Overview

* Tutorial

* How-to Guides

* Reference

* Workflow Triggers

* Workflow Queries

* Workflow Functions

* Pass Parameters to Workflows

* Run History

* Troubleshooting

* Overview

* Self-hosting Errors

* MongoDB Startup Error Post Migration to Version 5

* Schema Mismatch Error

* Kubernetes Helm Chart 3.0.4 Upgrade Error

* Recover admin access when you don't know the admin email

* Backup and Restore Errors

* License and Activation Errors

* Verify connectivity to cs.appsmith.com

* SSO and Authentication Errors

* User Management and Permissions Errors

* SSL, Certificate, and Reverse Proxy Errors

* Email and SMTP Errors

* Performance and Resource Errors

* Monitoring and Audit Log Errors

* Upgrade and Migration Errors

* Application Errors

* Product

* FAQ

* Security

* Telemetry

* Support at Appsmith

* Privacy Policy

* Release Notes

* Contribute

* Troubleshooting

* Self-hosting Errors

* Upgrade and Migration Errors
On this page
Upgrade and Migration Errors

This page shows how to resolve common errors when upgrading or migrating a self-hosted Appsmith instance. Before any upgrade or migration, always take a backup of your instance so you can roll back. See Backup instance and Upgrade Appsmith versions .

Backend down with aborted migration after upgrade

ABORTED MIGRATION

Cause

During an upgrade, Appsmith runs one-time database migrations. If a migration does not complete (or is skipped/aborted), the backend can fail to start, and the log shows changeset entries being PASSED OVER followed by an aborted migration. The root cause in these cases was the migration script not running to completion during the version change.

Solution

* Restore your pre-upgrade backup to return to a working state, then retry the upgrade. See Restore instance .

* Update directly to the latest version, since fixes for migration failures are shipped in newer releases. See Upgrade Appsmith versions .

* If your current version is older than v1.9.2, you must first follow the Upgrade to Checkpoint Version (v1.9.2) guide, as skipping the mandatory checkpoint can leave migrations in an inconsistent state.

* If your current version is newer than v1.9.2 but older than v1.96, first upgrade to any version from v1.96 through v1.99 (v1.99 is recommended), and then upgrade to 2.0 or newer. See Upgrade Appsmith versions .

* If the backend still fails after upgrading, gather full server logs and contact support.

Errors or missing plugins after downgrading by changing the image tag

Cause

Appsmith migrations are designed to run only once. If you upgrade and then downgrade by simply changing the image tag back to an older version, the database may already contain data that has been migrated to the newer schema, which the older version cannot read. This produces application errors (for example, missing plugins, or reset workspace/organization data) and can break the instance even after returning to the new version.

Solution

* Do not downgrade by only changing the image tag. The supported way to roll back is to restore the backup you took before upgrading. See Restore instance .

* If you have already downgraded without restoring a backup and are seeing errors, the recommended path is to upgrade back to the latest version and address the original issue there, with support's help. A migration that already ran once will not repeat automatically, so contact support via the chat widget if the instance remains in a broken state.

"Unable to invoke Cipher due to bad padding" after restoring a backup

Unable to invoke Cipher due to bad padding

Cause

This appears after restoring a backup into an instance whose encryption credentials don't match the backup. A common cause during migration between environments is that the target instance is using different APPSMITH_ENCRYPTION_PASSWORD and APPSMITH_ENCRYPTION_SALT values than the instance the backup was taken from, so the restored data cannot be decrypted.

Solution

* When restoring a backup, the target instance's APPSMITH_ENCRYPTION_PASSWORD and APPSMITH_ENCRYPTION_SALT must match the values from the instance that produced the backup. Update these in docker.env to the backed-up values and restart.

* For the full troubleshooting steps and other causes of this error, see Deployment Errors .

* Be careful when restoring backups across environments: restoring a backup also restores that environment's data and requires that environment's encryption keys.

Upgrading directly to the latest version vs stepping through releases

Cause

Users on very old versions are sometimes unsure whether they must step through intermediate versions, and instances configured with a floating image tag can upgrade unexpectedly.

Solution

* You can update directly from an old version to the latest in a single step; you do not need to go through every intermediate version. The exception is the mandatory checkpoint: if you are older than v1.9.2, first follow Upgrade to Checkpoint Version (v1.9.2) . For Docker, there is also a v1.96 to v1.99 checkpoint required before moving to 2.0+, described in Upgrade Appsmith versions .

* Pin the image tag to a specific release (for example index.docker.io/appsmith/appsmith-ee:<version> ) instead of a floating tag, so restarts don't pull an unexpected version. Find release tags on GitHub .

* Always take a backup before updating. See Backup instance .

"unauthorized" when pulling the image while upgrading from Community to Commercial

unauthorized: incorrect username or password

Cause

This occurs when switching from the Community image ( appsmith-ce ) to the Commercial image ( appsmith-ee ) without following the documented upgrade procedure, for example using an image reference with an empty or invalid tag.

Solution

* Follow the documented upgrade-from-Community procedure, which covers signing up for a license and updating the image correctly: Upgrade from Community Appsmith (Docker) . For Kubernetes, see Upgrade from Community Appsmith (Kubernetes) .

* Pin the appsmith-ee image to a specific release tag rather than leaving the tag empty or set to a floating value. Find release tags on GitHub .

* Note that you can run the appsmith-ee image under the free plan with the same features as the Community edition, which makes future upgrades or downgrades between plans seamless.

Cannot import an app exported from a newer version into an older instance

Cause

Appsmith application exports are not backward compatible. An application JSON exported from a newer Appsmith version cannot be imported into an instance running an older version. This commonly affects air-gapped instances and migrations from Appsmith Cloud (which always runs the latest version) to an older self-hosted instance.

Solution

* Import into an instance running the same version or newer than the source, not older. For air-gapped or self-hosted targets, develop the app on an instance at the same version (or older) than the destination.

* To bring an older instance up to date before importing, see Upgrade Appsmith versions .

Was this page helpful?

Edit this page

Previous
Monitoring and Audit Log Errors
Next
Application Errors

* Backend down with aborted migration after upgrade

* Errors or missing plugins after downgrading by changing the image tag

* "Unable to invoke Cipher due to bad padding" after restoring a backup

* Upgrading directly to the latest version vs stepping through releases

* "unauthorized" when pulling the image while upgrading from Community to Commercial

* Cannot import an app exported from a newer version into an older instance

Links found on this page

Skip to main content [direct]
Try Appsmith [direct]
Get Started [direct]
Build Your First App [direct]
Self Hosting [direct]
New Installation Guides [direct]
Manage Installation [direct]
Upgrade Installation Guides [direct]
Concepts [direct]
Connect Data [direct]
How-to Guides [direct]
Reference [direct]
Query Settings [direct]
Concepts [direct]
Build Apps [direct]
Quickstart [direct]
How-to Guides [direct]
Reference [direct]
Widgets [direct]
Accessibility [direct]
Theme [direct]
Sample Apps [direct]
Write Code [direct]
How-to Guides [direct]
Reference [direct]
Global Objects [direct]
Global Functions [direct]
JS Libraries [direct]
Fetch API [direct]
Data Transformation [direct]
JavaScript Settings [direct]
Concepts [direct]
Best Practices [direct]
Manage Apps and Users [direct]
Granular Access Control [direct]
Versioning with Git [direct]
Setup SCIM Provisioning [direct]
Embed Appsmith [direct]
Migrate Applications [direct]
Audit Logs [direct]
Branding [direct]
External Client Portal [direct]
Packages [direct]
Tutorial [direct]
How-to Guides [direct]
Reference [direct]
GIT Apps with Packages Best Practices [direct]
Code Packages [direct]
UI Packages [direct]
Workflows [direct]
Tutorial [direct]
How-to Guides [direct]
Reference [direct]
Workflow Queries [direct]
Workflow Functions [direct]
Pass Parameters to Workflows [direct]
Run History [direct]
Troubleshooting [direct]
Self-hosting Errors [direct]
MongoDB Startup Error Post Migration to Version 5 [direct]
Schema Mismatch Error [direct]
Kubernetes Helm Chart 3.0.4 Upgrade Error [direct]
Recover admin access when you don't know the admin email [direct]
Backup and Restore Errors [direct]
License and Activation Errors [direct]
Verify connectivity to cs.appsmith.com [direct]
SSO and Authentication Errors [direct]
User Management and Permissions Errors [direct]
SSL, Certificate, and Reverse Proxy Errors [direct]
Email and SMTP Errors [direct]
Performance and Resource Errors [direct]
Monitoring and Audit Log Errors [direct]
Application Errors [direct]
Product [direct]
Security [direct]
Telemetry [direct]
Support at Appsmith [direct]
Privacy Policy [direct]
Release Notes [direct]
Contribute [direct]