apache/cassandra · error · AlreadyExistsException

Already exists

Error message

Already exists

What it means

Thrown as an AlreadyExistsException by a CreateKeyspace schema transformation when the target keyspace already exists in the current schema and ignoreIfExists is false. It prevents silently overwriting existing keyspace metadata during schema changes.

Solutions

1. Add IF NOT EXISTS to the CREATE KEYSPACE statement (sets ignoreIfExists=true)
2. Check Schema.instance.getNullableKeyspaceMetadata(name) before issuing the creation
3. Catch AlreadyExistsException and treat it as a no-op if creation is idempotent in your tooling
4. Use a different keyspace name if a genuinely new keyspace was intended

Example fix

// before
CREATE KEYSPACE my_ks WITH replication = {'class': 'SimpleStrategy', 'replication_factor': 3};
// after
CREATE KEYSPACE IF NOT EXISTS my_ks WITH replication = {'class': 'SimpleStrategy', 'replication_factor': 3};

if (Schema.instance.getNullableKeyspaceMetadata(ksName) != null) { /* already exists: skip */ }

boolean keyspaceExists(String ks) { return Schema.instance.getNullableKeyspaceMetadata(ks) != null; }

try { schemaChange(createKeyspaceCql); } catch (AlreadyExistsException e) { log.info("keyspace already present, continuing"); }

When it happens

Trigger: Calling SchemaTransformations.createKeyspace(keyspace, ignoreIfExists=false).apply() (e.g. via a CREATE KEYSPACE statement without IF NOT EXISTS) when schema.getNullable(keyspace.name) returns existing metadata.

Common situations: Running CREATE KEYSPACE without IF NOT EXISTS on an existing keyspace; re-running an initialization script; racing concurrent setup processes where two nodes apply the same keyspace creation.

Understand the failure class

Background: "already exists" / EEXIST / FileAlreadyExistsException: what the 'file already exists' error means and how to fix it — this error's family across 37 libraries.

Related errors

• ACCESS TO DATACENTERS operations not supported by…
• Aggregate ' ' already exists
• ALREADY_EXISTS
• Because of this name
• Cannot add new field

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

Appendix: source

Thrown at src/java/org/apache/cassandra/schema/SchemaTransformations.java:59

     *                       {@code keyspace} already exists in the schema the transformation is applied on. Otherwise,
     *                       the transformation throws an {@link AlreadyExistsException} in that case.
     * @return the created transformation.
     */
    public static SchemaTransformation addKeyspace(KeyspaceMetadata keyspace, boolean ignoreIfExists)
    {
        return new SchemaTransformation()
        {
            @Override
            public Keyspaces apply(ClusterMetadata metadata)
            {
                Keyspaces schema = metadata.schema.getKeyspaces();
                KeyspaceMetadata existing = schema.getNullable(keyspace.name);
                if (existing != null)
                {
                    if (ignoreIfExists)
                        return schema;

                    throw new AlreadyExistsException(keyspace.name);
                }

                return schema.withAddedOrUpdated(keyspace);
            }

            @Override
            public boolean compatibleWith(ClusterMetadata metadata)
            {
                return metadata.directory.commonSerializationVersion.isAtLeast(Version.V0);
            }
        };
    }

    /**
     * Creates a schema transformation that adds the provided table.
     *
     * @param table          the table to add.
     * @param ignoreIfExists if {@code true}, the transformation is a no-op if a table of the same name than

View on GitHub (pinned to 88fd0f6a0e)