Upgrading to new naming convention – How to solve related issues

Opster Team

Feb-20, Version: 1.7-8.0

Before you begin reading this guide, we recommend you run Elasticsearch Error Check-Up which analyzes 2 JSON files to detect many errors.

Briefly, this error occurs when Elasticsearch is upgraded to a new version, and the new version uses a different naming convention for configuration settings or other internal elements. The error indicates that the upgrade process was unable to automatically convert the old naming convention to the new one, and some manual intervention is required to complete the upgrade. To resolve this issue, the user should consult the Elasticsearch documentation for guidance on how to perform the upgrade, paying particular attention to any changes in naming conventions.

To easily locate the root cause and resolve this issue try AutoOps for Elasticsearch & OpenSearch. It diagnoses problems by analyzing hundreds of metrics collected by a lightweight agent and offers guidance for resolving them.

This guide will help you check for common problems that cause the log ” Upgrading to new naming convention ” to appear. To understand the issues related to this log, read the explanation below about the following Elasticsearch concepts: index.

Log Context

Log “{} upgrading [{}] to new naming convention” classname is IndexFolderUpgrader.java.
We extracted the following from Elasticsearch source code for those seeking an in-depth context :

             final Path indexFolderPath = nodePath.indicesPath.resolve(indexFolderName);
            final IndexMetaData indexMetaData = IndexMetaData.FORMAT.loadLatestState(logger; indexFolderPath);
            if (indexMetaData != null) {
                final Index index = indexMetaData.getIndex();
                if (needsUpgrade(index; indexFolderName)) {
                    logger.info("{} upgrading [{}] to new naming convention"; index; indexFolderPath);
                    final IndexSettings indexSettings = new IndexSettings(indexMetaData; settings);
                    if (indexSettings.hasCustomDataPath()) {
                        // we rename index folder in custom path before renaming them in any node path
                        // to have the index state under a not-yet-upgraded index folder; which we use to
                        // continue renaming after a incomplete upgrade.


Watch product tour

Try AutoOps to find & fix Elasticsearch problems

Analyze Your Cluster
Skip to content