Skip to content

Migration recovery on startup#

Lens Desktop stores local state (preferences, cluster lists, integrations, hotbars) in files that are migrated forward when a release changes their format. If the migration cannot complete cleanly (for example, after a crash during a previous run or an interrupted upgrade), Lens Desktop falls back to a safe state at startup and shows a notification telling you a recovery occurred.

What to expect#

  • Lens Desktop opens normally and is fully usable.
  • A notification confirms that local state was recovered. You can dismiss it.
  • Some items that depend on the unmigrated data may need to be re-added (for example, the order of hotbar entries, or recent search history).

When to take action#

  • Cluster lists are missing. Re-add the affected cloud integration or kubeconfig from Kubernetes Clusters.
  • Lens Prism providers are missing. Re-add them from Preferences > Integrations > AI & Intelligence Integrations.
  • Repeated recovery notifications across multiple launches. Quit Lens Desktop and contact support with your logs so the root cause can be identified.

How to avoid it#

Recovery is automatic and safe, so most users do not need to take preventive action. If you see recoveries often:

  • Close Lens Desktop normally (quit instead of force-quit) when possible.
  • Make sure your home directory has enough free space. Migrations write temporary files alongside the originals.
  • Keep Lens Desktop up to date so you benefit from the latest migration logic.