pinpoint-apm/pinpoint · error · InvalidHbaseSchemaException

Duplicate ColumnFamily name :

Error message

Duplicate ColumnFamily name : 

What it means

Thrown by TableChangeMapper.mapColumnFamilies when two <createColumnFamily> elements within the same table change use the same name. HBase column family names must be unique per table, and the mapper detects this while assembling ColumnFamilyChange objects into a LinkedHashMap keyed by name.

Source

Thrown at hbase/hbase-schema/src/main/java/com/navercorp/pinpoint/hbase/schema/reader/xml/mapper/TableChangeMapper.java:78

        }

        TableConfiguration tableConfiguration = tableConfigurationMapper.mapConfiguration(createTable.getConfiguration());
        List<ColumnFamilyChange> columnFamilyChanges = mapColumnFamilies(createTable.getCreateColumnFamily());
        CreateTableChange.SplitOption splitOption = splitOptionMapper.mapSplitOption(createTable.getSplit());

        return new CreateTableChange(tableName, tableConfiguration, columnFamilyChanges, splitOption);
    }

    private List<ColumnFamilyChange> mapColumnFamilies(List<Table.CreateColumnFamily> createColumnFamilies) {
        if (CollectionUtils.isEmpty(createColumnFamilies)) {
            return Collections.emptyList();
        }
        Map<String, ColumnFamilyChange> createColumnFamilyChanges = new LinkedHashMap<>();
        for (Table.CreateColumnFamily createColumnFamily : createColumnFamilies) {
            String columnFamilyName = createColumnFamily.getName();
            ColumnFamilyChange columnFamilyChange = columnFamilyChangeMapper.mapCreate(createColumnFamily);
            if (createColumnFamilyChanges.put(columnFamilyName, columnFamilyChange) != null) {
                throw new InvalidHbaseSchemaException("Duplicate ColumnFamily name : " + columnFamilyName);
            }
        }
        return new ArrayList<>(createColumnFamilyChanges.values());
    }
}

View on GitHub (pinned to 744c3d3075)

Solutions

1. Rename one of the duplicated <createColumnFamily> elements so names are unique within the table change.
2. If the intent was to modify an existing family, that family should appear only once — remove the redundant entry.
3. Add CI validation that maps all schema XML to surface duplicates before release.

Example fix

<!-- before -->
<createColumnFamily name="AgentInfo"/>
<createColumnFamily name="AgentInfo"/>
<!-- after -->
<createColumnFamily name="AgentInfo"/>
<createColumnFamily name="AgentEvent"/>

Set<String> families = new HashSet<>();
for (Table.CreateColumnFamily cf : tableChange.getCreateColumnFamily()) {
    if (!families.add(cf.getName())) {
        throw new IllegalArgumentException("Duplicate column family: " + cf.getName());
    }
}

try { mapper.mapColumnFamilies(createColumnFamilies); } catch (InvalidHbaseSchemaException e) { log.error("Fix duplicate column family: {}", e.getMessage()); }

When it happens

Trigger: A <modifyTable> or <createTable> change lists two <createColumnFamily name="X"/> entries with an identical name.

Common situations: Copy-pasting a columnFamily block to add a similar family and forgetting to rename it; merging schema branches that both added the same family; generating XML from metadata that contains duplicate families.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• modifyTable :
• createTable :
• ColumnFamily name must not be empty
• Duplicate include file :
• Duplicate changeSet id :

AI-assisted analysis of pinpoint-apm/pinpoint@744c3d3075 (2026-09-07). Data as JSON: /api/errors/864b77cd33383b06. Report an issue: GitHub.