apache/cassandra · error · ConfigurationException

Config contains both old and new keys for the same configura

Error message

Config contains both old and new keys for the same configuration parameters, migrate old -> new: <duplicates>

What it means

During config load, Cassandra detects that the yaml contains both a deprecated/old key and its renamed (new) equivalent for the same parameter. Because it cannot decide which value wins, it throws unless the flag cassandra.allow_new_old_config_keys (ALLOW_NEW_OLD_CONFIG_KEYS) is set, in which case it only logs a warning. This enforces migration to the new unified key names.

Source

Thrown at src/java/org/apache/cassandra/config/YamlConfigurationLoader.java:310

        List<String> duplicates = new ArrayList<>();
        for (Map.Entry<Class<?>, Map<String, Replacement>> outerEntry : replacements.entrySet())
        {
            for (Map.Entry<String, Replacement> entry : outerEntry.getValue().entrySet())
            {
                Replacement r = entry.getValue();
                if (!r.isValueFormatReplacement() && rawConfig.containsKey(r.oldName) && rawConfig.containsKey(r.newName))
                {
                    String msg = String.format("[%s -> %s]", r.oldName, r.newName);
                    duplicates.add(msg);
                }
            }
        }

        if (!duplicates.isEmpty())
        {
            String msg = String.format("Config contains both old and new keys for the same configuration parameters, migrate old -> new: %s", String.join(", ", duplicates));
            if (!ALLOW_NEW_OLD_CONFIG_KEYS.getBoolean())
                throw new ConfigurationException(msg);
            else
                logger.warn(msg);
        }
    }

    private static void verifyReplacements(Map<Class<?>, Map<String, Replacement>> replacements, byte[] configBytes)
    {
        LoaderOptions loaderOptions = getDefaultLoaderOptions();
        loaderOptions.setAllowDuplicateKeys(ALLOW_DUPLICATE_CONFIG_KEYS.getBoolean());
        Yaml rawYaml = new Yaml(loaderOptions);

        Map<String, Object> rawConfig = rawYaml.load(new ByteArrayInputStream(configBytes));
        if (rawConfig == null)
            rawConfig = new HashMap<>();
        verifyReplacements(replacements, rawConfig);

    }

View on GitHub (pinned to 88fd0f6a0e)

Solutions

  1. Remove the old key and keep only the new (renamed) key in cassandra.yaml
  2. Check NEWS.txt / the Replacement-annotated Config fields for the old->new mapping of the listed duplicate keys
  3. Temporarily set the system property cassandra.allow_new_old_config_keys=true to warn instead of fail while migrating (not a permanent fix)
  4. Search the yaml for each key named in the message and delete the deprecated occurrence

Example fix

// before (cassandra.yaml)
hinted_handoff_enabled: true
max_hint_window_in_ms: 10800000
hinted_handoff_throttle_in_kb: 1024
// after (migrate old -> new)
hinted_handoff_enabled: true
max_hint_window: 10800000ms
hinted_handoff_throttle: 1024KiB
Defensive patterns

Strategy: validation

Validate before calling

// fail startup early if both old and new keys appear
String yaml = java.nio.file.Files.readString(Path.of("cassandra.yaml"));
List<String> pairs = List.of("max_hint_window_in_ms:max_hint_window");
for (String p : pairs) {
    var parts = p.split(":");
    if (yaml.contains(parts[0]) && yaml.contains(parts[1]))
        throw new IllegalStateException("Both old and new key present: " + p);
}

Try / catch

try {
    config = loader.loadConfig(url);
} catch (ConfigurationException e) {
    if (e.getMessage().startsWith("Config contains both old and new keys"))
        log.error("Migrate deprecated keys per NEWS.txt: " + e.getMessage());
    throw e;
}

Prevention

When it happens

Trigger: loadConfig -> verifyReplacements finding e.g. both 'commitlog_sync_period_in_ms' and its replacement in the same yaml; also reachable via fromMap/updateFromMap when programmatically updating Config with both spellings; thrown only when the boolean config ALLOW_NEW_OLD_CONFIG_KEYS is false (default).

Common situations: Upgrading from Cassandra 4.x to 5.x without migrating renamed config keys; merge conflicts or sed scripts that appended new keys while leaving old ones; documentation referencing old names.

Understand the failure class

Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.

Related errors

AI-assisted analysis of apache/cassandra@88fd0f6a0e (2026-09-10). Data as JSON: /api/errors/ed03dfcc32708570. Report an issue: GitHub.