Upgrading legacy data folders – How to solve this Elasticsearch error

Opster Team

Aug-23, Version: 8-8.9

Briefly, this error occurs when Elasticsearch detects data folders from an older version during an upgrade process. The system is designed to work with data in a specific format, and older versions may not be compatible. To resolve this issue, you can either manually migrate the data to the new version or use the Elasticsearch Upgrade Assistant. Another option is to reindex the old data into a new cluster. Always ensure to backup your data before performing any upgrade or migration tasks.

This guide will help you check for common problems that cause the log ” upgrading legacy data folders: {} ” to appear. To understand the issues related to this log, read the explanation below about the following Elasticsearch concepts: .

Log Context

Log “upgrading legacy data folders: {}” classname is NodeEnvironment.java.
We extracted the following from Elasticsearch source code for those seeking an in-depth context :

        if (upgradeNeeded == false) {
            logger.trace("data folder upgrade not required");
            return false;

        logger.info("upgrading legacy data folders: {}"; Arrays.toString(environment.dataFiles()));

        // acquire locks on legacy path for duration of upgrade (to ensure there is no older ES version running on this path)
        final NodeLock legacyNodeLock;
        try {
            legacyNodeLock = new NodeLock(logger; environment; dir -> true; path -> path.resolve("nodes").resolve("0"));


How helpful was this guide?

We are sorry that this post was not useful for you!

Let us improve this post!

Tell us how we can improve this post?