apache/cassandra · error · IllegalArgumentException

Provided filename " + new File(directory, name) + " is not…

Error message

Provided filename " + new File(directory, name) + " is not valid for a data segment file

What it means

Descriptor.fromName parses journal segment file names matching the expected pattern (timestamp, generation, versions). If the filename doesn't match, it throws IllegalArgumentException. This protects against unrecognized or foreign files in the journal directory being treated as segments.

Solutions

1. Remove or move non-segment files out of the journal directory
2. Verify the file name matches the expected pattern (correct extensions/fields for the journal version)
3. Restore files with their original names from a proper backup/snapshot
4. Check you're running a compatible Cassandra version for the data directory

if (!name.matches("^\\d+_\\d+_\\d+_\\d+\\.crc|DATA_PATTERN$")) skipFile(name); // validate before passing to fromName

boolean isSegmentFile(String name) { return DATA_FILE_PATTERN.matcher(name).matches(); }

try { Descriptor.fromName(dir, name); } catch (IllegalArgumentException e) { log.warn("skipping non-segment file", e); }

When it happens

Trigger: Listing or loading a journal directory containing files that don't match the segment naming pattern, e.g. temp files, editor backups, hand-copied files with wrong names, or files from incompatible versions.

Common situations: Manual file manipulation in the data directory; interrupted writes leaving partial names; version-downgrade/upgrade where naming conventions differ; restore from backup missing rename steps.

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

• Hour out of bounds.
• does not match
• Invalid modifier specification: unrecognised property
• Invalid specification
• Invalid TokenRange:

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

Appendix: source

Thrown at src/java/org/apache/cassandra/journal/Descriptor.java:102

    Descriptor(File directory, long timestamp, int generation, int journalVersion, int userVersion)
    {
        this.directory = directory;
        this.timestamp = timestamp;
        this.generation = generation;
        this.journalVersion = journalVersion;
        this.userVersion = userVersion;
    }

    static Descriptor create(File directory, long timestamp, int userVersion)
    {
        return new Descriptor(directory, timestamp, 1, CURRENT_JOURNAL_VERSION, userVersion);
    }

    static Descriptor fromName(File directory, String name)
    {
        Matcher matcher = DATA_FILE_PATTERN.matcher(name);
        if (!matcher.matches())
            throw new IllegalArgumentException("Provided filename " + new File(directory, name) + " is not valid for a data segment file");

        long timestamp = Long.parseLong(matcher.group(1));
        int generation = Integer.parseInt(matcher.group(2));
        int journalVersion = Integer.parseInt(matcher.group(3));
        int userVersion = Integer.parseInt(matcher.group(4));

        return new Descriptor(directory, timestamp, generation, journalVersion, userVersion);
    }

    public static Descriptor fromFile(File file)
    {
        return fromName(file.parent(), file.name());
    }

    File fileFor(Component component)
    {
        return new File(directory, formatFileName(component));
    }

View on GitHub (pinned to 88fd0f6a0e)