apache/cassandra · error · IllegalArgumentException

Format must be one of %s

Error message

Format must be one of %s

What it means

AsyncProfilerService.parseFormat validates the user-supplied profiling output format against the known AsyncProfilerFormat enum values. When the raw format string does not match any enum constant, valueOf throws IllegalArgumentException and the service re-throws with a message listing all valid formats. It guards the 'format' start parameter of the async-profiler MBean API.

Source

Thrown at src/java/org/apache/cassandra/service/AsyncProfilerService.java:204

        }
    }

    public enum AsyncProfilerFormat
    {
        flat, traces, collapsed, flamegraph, tree, jfr;

        public static String parseFormat(String rawFormat)
        {
            if (rawFormat == null || rawFormat.isBlank())
                throw new IllegalArgumentException("Event can not be null nor blank string.");

            try
            {
                return AsyncProfilerFormat.valueOf(rawFormat).name();
            }
            catch (IllegalArgumentException ex)
            {
                throw new IllegalArgumentException(format("Format must be one of %s", VALID_FORMATS));
            }
        }
    }

    @Override
    public synchronized boolean start(Map<String, String> parameters)
    {
        if (isRunning())
            return false;

        validateStartParameters(parameters);

        try
        {
            run(new ThrowingFunction<>()
            {
                @Override
                public Object apply(AsyncProfiler profiler) throws Throwable

View on GitHub (pinned to 88fd0f6a0e)

Solutions

  1. Check the exception/VALID_FORMATS list and pass an exact enum name (e.g. 'flamegraph', 'tree', 'collapsed')
  2. Match case exactly — the lookup uses AsyncProfilerFormat.valueOf, which is case-sensitive
  3. Upgrade/align Cassandra version if your tooling uses a format from a different version
  4. Catch IllegalArgumentException in your tooling and retry with a valid default format

Example fix

// before
params.put("format", "FlameGraph");
// after
params.put("format", "flamegraph");
Defensive patterns

Strategy: validation

Validate before calling

Set<String> valid = AsyncProfilerService.VALID_FORMATS; // or list AsyncProfilerFormat values
if (format == null || !valid.contains(format)) throw new IllegalArgumentException("format must be one of " + valid);

Try / catch

try { svc.apply(params, file); } catch (IllegalArgumentException e) { if (e.getMessage().startsWith("Format must be one of")) { params.put("format", "flamegraph"); svc.apply(params, file); } else throw e; }

Prevention

When it happens

Trigger: Calling MBean start()/cmd() (or testAdvancedModeEnabledSuccess-style apply flows) with parameters map containing format=<value> where <value> is not one of the AsyncProfilerFormat constant names (e.g. 'tree' vs 'flamegraph', typos, wrong case).

Common situations: Typo in the format name; copying an async-profiler CLI option name that differs from the enum name; case-sensitivity mistakes (valueOf is case-sensitive); documentation drift across Cassandra versions when new formats were added.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

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