apache/cassandra · warning

Found unknown system directory

Error message

Found unknown system directory {}.{} at {} - this is likely left over from a previous version of Cassandra and should be removed after inspection.

What it means

During startup Cassandra walks the data directories and validates that every keyspace/table subdirectory belongs to a known system table. Directories under the 'system' keyspace that are not recognized are warned as likely leftovers from a previous Cassandra version, while unknown non-system directories get a softer message. This catches stale metadata (e.g. from a botched upgrade) that could confuse schema handling.

Solutions

1. Back up, then inspect the flagged directory contents before deleting
2. If confirmed leftover from an old version, remove the directory while the node is stopped
3. Verify schema upgraded cleanly (check system_schema tables); run upgradesstables if needed
4. If the directory holds needed data, use sstableloader to re-import it into a current table

Example fix

// before (node stopped)
/var/lib/cassandra/data/system/local-abc123/   # unknown system table

// after
$ cp -r /var/lib/cassandra/data/system/local-abc123 /backup/
$ rm -rf /var/lib/cassandra/data/system/local-abc123
$ .build/build-jars.sh -s && bin/cassandra   # restart, warning gone

// before upgrade: list system dirs and compare with known system tables
ls /var/lib/cassandra/data/system/ | while read d; do
  echo "$d"; # diff against system_schema tables of target version

When it happens

Trigger: A directory under the data dir matches a 'system'-keyspace table name that the current version does not recognize (e.g. after downgrade or partial upgrade), triggering the warn in the Files.walkFileTree visitor with SKIP_SUBTREE.

Common situations: Upgrading from an older Cassandra version where a system table was removed; a downgrade left system table data behind; manual copying of data dirs between clusters/versions.

Related errors

• 3
• Could not perform startup sequence and join cluster
• Directory doesn't exist
• ERR_WRONG_DISK_STATE
• ERR_WRONG_DISK_STATE

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

Appendix: source

Thrown at src/java/org/apache/cassandra/service/StartupChecks.java:1001

                        // In very old versions of Cassandra, we wouldn't necessarily delete sstables from dropped system tables
                        // which were removed in various major version upgrades (e.g system.Versions in 1.2)
                        if (ksPart.equals(SchemaConstants.SYSTEM_KEYSPACE_NAME) && !SystemKeyspace.ALL_TABLE_NAMES.contains(tablePart))
                        {
                            String canonicalPath = FileUtils.getCanonicalPath(new File(dir));

                            // We can have snapshots of our system tables or snapshots created with a -t tag of "system" that would trigger
                            // this potential warning, so we warn more softly in the case that it's probably a snapshot.
                            if (canonicalPath.contains("snapshot"))
                            {
                                logger.info("Found unknown system directory {}.{} at {} that contains the word snapshot. " +
                                            "This may be left over from a previous version of Cassandra or may be normal. " +
                                            " Consider removing after inspection if determined to be unnecessary.",
                                            ksPart, tablePart, canonicalPath);
                            }
                            else
                            {
                                logger.warn("Found unknown system directory {}.{} at {} - this is likely left over from a previous " +
                                            "version of Cassandra and should be removed after inspection.",
                                            ksPart, tablePart, canonicalPath);
                            }
                            return FileVisitResult.SKIP_SUBTREE;
                        }
                    }

                    String name = dir.getFileName().toString();
                    return (name.equals(Directories.SNAPSHOT_SUBDIR)
                            || name.equals(Directories.BACKUPS_SUBDIR)
                            || nonSSTablePaths.contains(PathUtils.toCanonicalPath(dir).toString()))
                           ? FileVisitResult.SKIP_SUBTREE
                           : FileVisitResult.CONTINUE;
                }
            };

            for (String dataDir : DatabaseDescriptor.getAllDataFileLocations())
            {

View on GitHub (pinned to 88fd0f6a0e)