pinpoint-apm/pinpoint · error · InvalidHbaseSchemaException

ColumnFamily name must not be empty

Error message

ColumnFamily name must not be empty

What it means

ColumnFamilyChangeMapper.mapCreate validates that a <createColumnFamily> element has a non-empty name before building a CreateColumnFamilyChange. An empty name would create an unusable HBase column family descriptor, so it is rejected with InvalidHbaseSchemaException.

Source

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

import com.navercorp.pinpoint.hbase.schema.definition.xml.Table;
import com.navercorp.pinpoint.hbase.schema.reader.InvalidHbaseSchemaException;
import com.navercorp.pinpoint.hbase.schema.reader.core.ColumnFamilyChange;
import com.navercorp.pinpoint.hbase.schema.reader.core.ColumnFamilyConfiguration;
import com.navercorp.pinpoint.hbase.schema.reader.core.CreateColumnFamilyChange;

import java.util.Objects;

/**
 * @author HyunGil Jeong
 */
public class ColumnFamilyChangeMapper {

    private final ColumnFamilyConfigurationMapper columnFamilyConfigurationMapper = new ColumnFamilyConfigurationMapper();

    public ColumnFamilyChange mapCreate(Table.CreateColumnFamily createColumnFamily) {
        Objects.requireNonNull(createColumnFamily, "createColumnFamily");
        if (StringUtils.isEmpty(createColumnFamily.getName())) {
            throw new InvalidHbaseSchemaException("ColumnFamily name must not be empty");
        }
        String name = createColumnFamily.getName();
        ColumnFamilyConfiguration columnFamilyConfiguration = columnFamilyConfigurationMapper.mapConfiguration(createColumnFamily.getConfiguration());

        return new CreateColumnFamilyChange(name, columnFamilyConfiguration);
    }
}

View on GitHub (pinned to 744c3d3075)

Solutions

1. Add the missing name attribute to the createColumnFamily element
2. Ensure the name is non-empty and uses valid HBase column family characters (no colons, printable bytes)
3. If the family is not actually needed, remove the createColumnFamily element entirely
4. Validate the schema XML against the XSD before applying change sets

Example fix

// before
<createColumnFamily name=""></createColumnFamily>
// after
<createColumnFamily name="AgentStatV2"></createColumnFamily>

for (Element cf : createColumnFamilyElements) {
    if (cf.getAttribute("name").trim().isEmpty()) {
        throw new IllegalArgumentException("createColumnFamily missing name");
    }
}

boolean hasName(Table.CreateColumnFamily cf) {
    return cf != null && !StringUtils.isEmpty(cf.getName());
}

try {
    ColumnFamilyChange c = mapper.mapCreate(createColumnFamily);
} catch (InvalidHbaseSchemaException e) {
    if (e.getMessage().contains("ColumnFamily name must not be empty")) {
        logger.error("createColumnFamily element missing name attribute");
    } else {
        throw e;
    }
}

When it happens

Trigger: Calling mapCreate with a Table.CreateColumnFamily whose getName() is null or empty — i.e. a createColumnFamily element missing the name attribute or with name="" in the change set XML.

Common situations: Copy-pasted createColumnFamily element with the name attribute accidentally deleted; placeholder name left empty in a template; XML editing tools stripping empty attributes.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

• modifyTable :
• createTable :
• Error loading change sets from
• Cyclic include detected for :
• Duplicate changeSet found. Id:

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