What causes "Configuration definition inherits unknown . A configuration can only extend one defined earlier or "default"." in apache/cassandra?

Define the inherited configuration earlier in the config map, or use the reserved name "default".

apache/cassandra · error · ConfigurationException

Configuration definition inherits unknown

Error message

Configuration definition inherits unknown <inherits>. A configuration can only extend one defined earlier or "default".

What it means

InheritingClass.resolve resolves an 'inherits' chain among ParameterizedClass configuration definitions. If the inherited name is absent from the provided map, ConfigurationException is thrown: a definition can only extend one that appears earlier in the config or the special "default". This prevents inheriting from unknown/undefined configurations.

Solutions

Define the inherited configuration earlier in the config map, or use the reserved name "default".
Fix the 'inherits' name spelling to match an existing definition.
Remove the 'inherits' key if inheritance is not needed.

Example fix

// before
my_encoder:
  class_name: MyEncoder
  inherits: base_encoder  # not defined
// after
my_encoder:
  class_name: MyEncoder
  inherits: default

Defensive patterns

Strategy: try-catch

Validate before calling

Map<String,ParameterizedClass> defs = ...;
if (def.inherits != null && !"default".equals(def.inherits) && !defs.containsKey(def.inherits))
    throw new ConfigurationException("inherits unknown parent: " + def.inherits);

Try / catch

try { cls.resolve(map); } catch (ConfigurationException e) { LOG.error("config inheritance broken: {}", e.getMessage()); throw e; }

Prevention

Define parent configurations before children in the config map
Only inherit from explicitly defined entries or the literal "default"
Grep the config for all 'inherits:' values and check each is defined

When it happens

Trigger: Setting 'inherits: someParent' on a config class (e.g. commitlog archiver, client config definitions) in cassandra.yaml where 'someParent' is not defined anywhere, or is defined later than the inheritor, or is misspelled.

Common situations: Renaming a base configuration without updating children; misspelling the parent name; ordering children before parents in the config; expecting an implicitly-defined default other than the literal "default".

Related errors

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

Appendix: source

Thrown at src/java/org/apache/cassandra/config/InheritingClass.java:54

    {
        super(class_name, parameters);
        this.inherits = inherits;
    }

    @SuppressWarnings("unused")
    public InheritingClass(Map<String, ?> p)
    {
        super(p);
        this.inherits = p.get("inherits").toString();
    }

    public ParameterizedClass resolve(Map<String, ParameterizedClass> map)
    {
        if (inherits == null)
            return this;
        ParameterizedClass parent = map.get(inherits);
        if (parent == null)
            throw new ConfigurationException("Configuration definition inherits unknown " + inherits
                                             + ". A configuration can only extend one defined earlier or \"default\".");
        Map<String, String> resolvedParameters;
        if (parameters == null || parameters.isEmpty())
            resolvedParameters = parent.parameters;
        else if (parent.parameters == null || parent.parameters.isEmpty())
            resolvedParameters = this.parameters;
        else
        {
            resolvedParameters = new LinkedHashMap<>(parent.parameters);
            resolvedParameters.putAll(this.parameters);
        }

        String resolvedClass = this.class_name == null ? parent.class_name : this.class_name;
        return new ParameterizedClass(resolvedClass, resolvedParameters);
    }

    @Override
    public String toString()

View on GitHub (pinned to 88fd0f6a0e)