pinpoint-apm/pinpoint · error · InvalidHbaseSchemaException

Duplicate include file :

Error message

Duplicate include file : 

What it means

Thrown by HbaseSchemaMapper.mapIncludeFiles when an XML hbase-schema definition file declares the same <include> file more than once. The mapper builds a LinkedHashSet of include files and fails fast to keep the include graph deterministic. It signals a validation error in the schema XML, not a runtime HBase problem.

Source

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

    public HbaseSchemaMapper(JAXBContext jaxbContext, Schema schema) {
        this.changeSetMapper = new ChangeSetMapper(jaxbContext, schema);
    }

    public XmlHbaseSchemaParseResult map(HbaseSchema hbaseSchema) {
        Set<String> includeFiles = mapIncludeFiles(hbaseSchema.getInclude());
        Collection<ChangeSet> changeSets = mapChangeSets(hbaseSchema.getChangeSet());
        return new XmlHbaseSchemaParseResult(includeFiles, changeSets);
    }

    private Set<String> mapIncludeFiles(List<HbaseSchema.Include> schemaIncludes) {
        if (CollectionUtils.isEmpty(schemaIncludes)) {
            return Collections.emptySet();
        }
        Set<String> includeFiles = new LinkedHashSet<>();
        for (HbaseSchema.Include schemaInclude : schemaIncludes) {
            String includeFile = schemaInclude.getFile();
            if (includeFiles.contains(includeFile)) {
                throw new InvalidHbaseSchemaException("Duplicate include file : " + includeFile);
            }
            includeFiles.add(includeFile);
        }
        return includeFiles;
    }

    private Collection<ChangeSet> mapChangeSets(List<com.navercorp.pinpoint.hbase.schema.definition.xml.ChangeSet> schemaChangeSets) {
        if (CollectionUtils.isEmpty(schemaChangeSets)) {
            return Collections.emptySet();
        }
        Map<String, ChangeSet> changeSets = new LinkedHashMap<>();
        for (com.navercorp.pinpoint.hbase.schema.definition.xml.ChangeSet schemaChangeSet : schemaChangeSets) {
            String changeSetId = schemaChangeSet.getId();
            if (changeSets.containsKey(changeSetId)) {
                throw new InvalidHbaseSchemaException("Duplicate changeSet id : " + changeSetId);
            }
            ChangeSet changeSet = changeSetMapper.mapChangeSet(schemaChangeSet);
            changeSets.put(changeSetId, changeSet);

View on GitHub (pinned to 744c3d3075)

Solutions

1. Open the schema XML and remove the duplicated <include file="..."> entry.
2. If two includes are genuinely needed, verify the file attribute values differ (e.g. different paths/files).
3. Validate the schema XML before deployment with the same reader used at runtime so the error surfaces in CI.

Example fix

<!-- before -->
<include file="schema-agent.xml"/>
<include file="schema-agent.xml"/>
<!-- after -->
<include file="schema-agent.xml"/>

Set<String> seen = new HashSet<>();
for (HbaseSchema.Include inc : schema.getIncludes()) {
    if (!seen.add(inc.getFile())) {
        throw new IllegalArgumentException("Duplicate include: " + inc.getFile());
    }
}

try { schema = hbaseSchemaReader.read(xml); } catch (InvalidHbaseSchemaException e) { log.error("Bad schema XML: {}", e.getMessage()); }

When it happens

Trigger: Loading (via HbaseSchemaReader/includeFiles) an XML schema where two <include file="..."> elements reference the identical file path within the same schema definition.

Common situations: Copy-pasting an include block in schema.xml while adding a new include; merging schema files from branches where both added the same include; forgetting to remove an old include after refactoring.

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 changeSet id :
• Table name must not be empty

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