What causes "Output file name must match pattern %s." in apache/cassandra?

Use a simple base file name matching the documented pattern (letters, digits, '-', '_', '.') with no slashes

apache/cassandra · error · IllegalArgumentException

Output file name must match pattern

Error message

Output file name must match pattern %s.

What it means

validateOutputFileName enforces VALID_FILENAME_REGEX_PATTERN so profiler output stays inside the profiles log directory and cannot contain path separators or illegal characters. A file name that is non-empty but does not match the allowed pattern (e.g. containing '/', '..', or special characters) triggers this IllegalArgumentException.

Solutions

Use a simple base file name matching the documented pattern (letters, digits, '-', '_', '.') with no slashes
Strip any directory components and pass only the base name
Prevalidate locally with the same regex shown in the exception message before calling

Example fix

// before
service.apply("start", "/tmp/prof/results.html");
// after
service.apply("start", "results.html");

Defensive patterns

Strategy: validation

Validate before calling

java.util.regex.Pattern P = AsyncProfilerService.VALID_FILENAME_REGEX_PATTERN; // mirror locally
if (outputFile == null || !P.matcher(outputFile).matches()) throw new IllegalArgumentException("bad output file name");

Try / catch

try { svc.apply(cmd, name); } catch (IllegalArgumentException e) { if (e.getMessage().contains("must match pattern")) { name = name.replaceAll("[^A-Za-z0-9._-]", "_"); svc.apply(cmd, name); } else throw e; }

Prevention

Use only simple base names: letters, digits, dot, dash, underscore
Never include directory separators or absolute paths
Sanitize generated names (timestamps etc.) against the pattern

When it happens

Trigger: Calling file()/apply() with names containing path separators, dots-segments, spaces or other characters disallowed by the regex — anything that could escape the log dir or break file creation.

Common situations: Users passing absolute paths or subdirectory paths as the output name; names generated with timestamps in unexpected formats; cross-platform path separators.

Understand the failure class

Background: "invalid id" errors: invalid identifier format — why libraries reject IDs before lookup, and how to fix them — this error's family across 37 libraries.

Related errors

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

Appendix: source

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

            {
                return asyncProfiler.execute("status");
            }
        });
    }

    @Override
    public synchronized boolean isEnabled()
    {
        return instance != null && asyncProfiler != null;
    }

    public static String validateOutputFileName(String outputFile)
    {
        if (outputFile == null || outputFile.trim().isEmpty())
            throw new IllegalArgumentException("Output file name must not be null or empty.");

        if (!VALID_FILENAME_REGEX_PATTERN.matcher(outputFile).matches())
            throw new IllegalArgumentException(format("Output file name must match pattern %s.", VALID_FILENAME_REGEX_PATTERN));

        return outputFile;
    }

    public static String validateCommand(String command)
    {
        if (command == null || command.isBlank())
            throw new IllegalArgumentException("Command can not be null or blank string.");

        return command;
    }

    /**
     * @param duration duration of profiling
     * @return converted string representation of duration to seconds
     */
    public static int parseDuration(String duration)
    {

View on GitHub (pinned to 88fd0f6a0e)