{"record":{"id":"8c3089be94cd078c","repo":"pinpoint-apm/pinpoint","slug":"cannot-add-an-existing-column-family","errorCode":null,"errorMessage":"Cannot add an existing column family : ","messagePattern":"Cannot add an existing column family : ","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"hbase/hbase-schema/src/main/java/com/navercorp/pinpoint/hbase/schema/core/command/TableCommand.java","lineNumber":100,"sourceCode":"        }\n        TableConfiguration.Durability durability = tableConfiguration.getDurability();\n        if (durability != null) {\n            builder.setDurability(Durability.valueOf(durability.name()));\n        }\n    }\n\n    void applyColumnFamilyChanges(List<ColumnFamilyChange> columnFamilyChanges) {\n        if (CollectionUtils.isEmpty(columnFamilyChanges)) {\n            return;\n        }\n        TableDescriptor tableDescriptor = builder.build();\n\n        for (ColumnFamilyChange columnFamilyChange : columnFamilyChanges) {\n            ChangeType changeType = columnFamilyChange.getType();\n            if (changeType == ChangeType.CREATE) {\n                ColumnFamilyDescriptor family = newColumnDescriptor(columnFamilyChange);\n                if (tableDescriptor.hasColumnFamily(family.getName())) {\n                    throw new IllegalArgumentException(\"Cannot add an existing column family : \" + tableDescriptor.getTableName().getNameAsString());\n                }\n                builder.setColumnFamily(family);\n            } else {\n                throw new UnsupportedOperationException(\"Unknown change type : \" + changeType);\n            }\n        }\n    }\n\n    private ColumnFamilyDescriptor newColumnDescriptor(ColumnFamilyChange columnFamilyChange) {\n        byte[] name = BytesUtils.toBytes(columnFamilyChange.getName());\n        ColumnFamilyDescriptorBuilder builder = ColumnFamilyDescriptorBuilder.newBuilder(name);\n\n        ColumnFamilyConfiguration columnFamilyConfiguration = columnFamilyChange.getColumnFamilyConfiguration();\n        Boolean blockCacheEnabled = columnFamilyConfiguration.getBlockCacheEnabled();\n        if (blockCacheEnabled != null) {\n            builder.setBlockCacheEnabled(blockCacheEnabled);\n        }\n        Integer replicationScope = columnFamilyConfiguration.getReplicationScope();","sourceCodeStart":82,"sourceCodeEnd":118,"githubUrl":"https://github.com/pinpoint-apm/pinpoint/blob/744c3d3075e595656abb1ae331ad2c0e4c9eb996/hbase/hbase-schema/src/main/java/com/navercorp/pinpoint/hbase/schema/core/command/TableCommand.java#L82-L118","documentation":"Thrown by TableCommand.applyColumnFamilyChanges when a schema change requests CREATE of a column family that already exists in the target table's descriptor. The library refuses to re-create an existing family instead of silently overwriting its configuration. This is a fail-fast guard for non-idempotent column family additions.","triggerScenarios":"Calling applyTableChange/applyColumnFamilyChanges with a ColumnFamilyChange of ChangeType.CREATE whose family name is already present in tableDescriptor (tableDescriptor.hasColumnFamily(family.getName()) is true).","commonSituations":"Re-running a change set that was already partially applied; two change sets both adding the same family name to a table; editing an existing column family's config but expressing it as CREATE instead of a modify operation; stale local schema state vs the actual HBase table.","solutions":["Remove the duplicate CREATE column family entry from the change set, or skip the change set since the family already exists","Express the change as an update/modify of the existing column family instead of CREATE","Check current table state (Admin.getDescriptor) before applying and filter out families that already exist","If the previous run failed midway, verify which changes were applied and start from the correct change set id"],"exampleFix":"// before\nnew ColumnFamilyChange(\"TestAgent\", ChangeType.CREATE, config) // family already on table\n// after\nif (!admin.getDescriptor(tableName).hasColumnFamily(Bytes.toBytes(\"TestAgent\"))) {\n    applyChange(new ColumnFamilyChange(\"TestAgent\", ChangeType.CREATE, config));\n}","handlingStrategy":"validation","validationCode":"HColumnDescriptor existing = descriptor.getFamily(Bytes.toBytes(familyName));\nif (existing != null) {\n    throw new IllegalStateException(\"Column family already exists: \" + familyName);\n}","typeGuard":"boolean canCreateFamily(TableDescriptor td, String name) {\n    return !td.hasColumnFamily(Bytes.toBytes(name));\n}","tryCatchPattern":"try {\n    command.applyTableChange(change);\n} catch (IllegalArgumentException e) {\n    if (e.getMessage().startsWith(\"Cannot add an existing column family\")) {\n        // skip or convert to update\n    } else {\n        throw e;\n    }\n}","preventionTips":["Check Admin.getDescriptor(...).hasColumnFamily before issuing CREATE changes","Keep applied change sets tracked so they are not re-run","Use a modify operation for configuration updates to existing families"],"tags":["hbase","schema","duplicate-column-family","illegal-argument"],"backgroundTag":"file-already-exists","analyzedSha":"744c3d3075e595656abb1ae331ad2c0e4c9eb996","analyzedAt":"2026-09-07T18:48:45.289Z","contentChangedAt":"2026-09-07T18:48:45.289Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}