pinpoint-apm/pinpoint · error · IllegalStateException

table not found. Initialization required.

Error message

 table not found. Initialization required.

What it means

Thrown by HbaseSchemaServiceImpl.assertInitialization when the schema change log table for the namespace does not exist yet (schemaChangeLogService.isAvailable returns false). Operations like update(), getChangeLogs(), and getChangeLog() require initialization first. It tells the caller to run schema initialization before using these APIs.

Solutions

1. Run the schema initialization path (update() against an empty/uninitialized namespace initializes it, or the dedicated init entry point) to create the change log table and apply base change sets.
2. Verify the namespace configuration points at the intended cluster/namespace where initialization was already performed.
3. Check in HBase shell that the change log table exists and the client has read access to it.

Example fix

// before
List<ChangeLog> logs = service.getChangeLogs(namespace); // IllegalStateException
// after
if (!schemaChangeLogService.isAvailable(namespace)) {
    service.update(); // performs initialization first
}
List<ChangeLog> logs = service.getChangeLogs(namespace);

if (!schemaChangeLogService.isAvailable(namespace)) {
    // run initialization first or fail fast with a clear message
    schemaService.update();
}

try { service.getChangeLogs(namespace); } catch (IllegalStateException e) {
    if (e.getMessage().endsWith("Initialization required.")) {
        service.update(); // initialize then retry once
        service.getChangeLogs(namespace);
    }
}

When it happens

Trigger: Calling update/getChangeLogs/getChangeLog against a namespace where the change-log table (per schemaChangeLogService.getTableName()) has never been created — i.e. before the first successful initialization run.

Common situations: Fresh HBase cluster or new namespace where the schema tool was never initialized; pointing the app at the wrong namespace/cluster; the change log table was accidentally dropped; HBase connectivity/permissions hiding the table.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• Already closed
• Cannot add an existing column family :
• Cannot create an existing table :
• Cannot modify a non-existent table :
• ColumnFamily name must not be empty

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

Appendix: source

Thrown at hbase/hbase-schema/src/main/java/com/navercorp/pinpoint/hbase/schema/service/HbaseSchemaServiceImpl.java:272

    }

    @Override
    public List<SchemaChangeLog> getChangeLogs(String namespace) {
        assertInitialization(namespace);
        return schemaChangeLogService.getSchemaChangeLogs(namespace);
    }

    @Override
    public SchemaChangeLog getChangeLog(String namespace, String changeSetId) {
        Assert.hasLength(changeSetId, "Change set must not be empty");
        assertInitialization(namespace);
        return schemaChangeLogService.getSchemaChangeLog(namespace, changeSetId);
    }

    private void assertInitialization(String namespace) {
        if (!schemaChangeLogService.isAvailable(namespace)) {
            String tableName = schemaChangeLogService.getTableName();
            throw new IllegalStateException(tableName + " table not found. Initialization required.");
        }
    }
}

View on GitHub (pinned to 744c3d3075)