apache/cassandra · error · ConfigurationException

%s requires a non-empty %s parameter

Error message

%s requires a non-empty %s parameter

What it means

PasswordDefaultRoleInitializer is configured via cassandra.yaml (role_name/password/password_hash under authenticator options). validateConfiguration() runs at startup and rejects a configuration where the default role name is null or empty, since it cannot create an anonymous default superuser.

Source

Thrown at src/java/org/apache/cassandra/auth/PasswordDefaultRoleInitializer.java:110

    @Override
    public void createDefaultRole()
    {
        QueryProcessor.process(createDefaultRoleQuery(), consistencyForRoleWrite(role));
        logger.info("Created default superuser role '{}'", role);
    }

    @Override
    public String defaultRoleName()
    {
        return role;
    }

    @Override
    public void validateConfiguration() throws ConfigurationException
    {
        if (Strings.isNullOrEmpty(role))
            throw new ConfigurationException(String.format("%s requires a non-empty %s parameter", getClass().getSimpleName(), ROLE));

        boolean specifiedPassword = !Strings.isNullOrEmpty(password);
        boolean specifiedPasswordHash = !Strings.isNullOrEmpty(passwordHash);

        if (!specifiedPassword && !specifiedPasswordHash)
            throw new ConfigurationException(String.format("There has to be one of %s, %s specified.", PASSWORD, PASSWORD_HASH));
        else if (specifiedPassword && specifiedPasswordHash)
            throw new ConfigurationException(String.format("Only one of %s, %s can be specified.", PASSWORD, PASSWORD_HASH));
    }

    @VisibleForTesting
    public String createDefaultRoleQuery()
    {
        return String.format("INSERT INTO %s.%s (role, is_superuser, can_login, salted_hash) VALUES ('%s', true, true, '%s') USING TIMESTAMP 0",
                             SchemaConstants.AUTH_KEYSPACE_NAME,
                             AuthKeyspace.ROLES,
                             escapeCqlLiteral(role),
                             escapeCqlLiteral(password == null ? passwordHash : hashpw(password)));

View on GitHub (pinned to 88fd0f6a0e)

Solutions

  1. Set a non-empty role_name under auth options in cassandra.yaml (e.g. role_name: cassandra)
  2. If you don't need a default role, remove/replace the default_role_initializer option rather than leaving an empty role_name
  3. Validate the yaml renders correctly (no templating blanks) before restart

Example fix

// before (cassandra.yaml)
role_name: ""
// after
cassandra:
  authenticator: PasswordAuthenticator
  role_manager: CassandraRoleManager
  options:
    role_name: cassandra
    password: ChangeMeNow
Defensive patterns

Strategy: validation

Validate before calling

String role = config.get("role_name"); if (role == null || role.trim().isEmpty()) fail("role_name required by PasswordDefaultRoleInitializer");

Type guard

boolean hasDefaultRoleName(Map<String,String> opts) { String r = opts.get("role_name"); return r != null && !r.trim().isEmpty(); }

Try / catch

try { config.validate(); } catch (ConfigurationException e) { log.error("yaml auth config invalid", e); System.exit(1); }

Prevention

When it happens

Trigger: Starting Cassandra with PasswordAuthenticator + PasswordDefaultRoleInitializer where role_name is missing, set to empty string, or whitespace-only.

Common situations: cassandra.yaml edited by hand with the role_name key removed or commented out; config templating tools rendering empty values; upgrading and merging yaml files incorrectly.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

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