Activiti/Activiti · error · ActivitiException

couldn't get activiti table names using metadata

Error message

couldn't get activiti table names using metadata: ${e.getMessage()}

What it means

Activiti wraps any Exception raised while reading JDBC DatabaseMetaData to list the tables owned by the engine into this ActivitiException. The engine calls DatabaseMetaData.getTables() during schema check/creation (e.g. databaseSchemaUpdate=true) and cannot recover if the metadata query fails. The original exception is chained as the cause.

Solutions

Check the chained cause (e.getCause()) to see the real JDBC error and fix the underlying connection or privilege problem
Verify databaseSchema/databaseCatalog/tablePrefix configuration matches your database
Grant the DB user metadata read privileges (e.g. SELECT on information_schema or system catalog views)
Test the datasource connection with a simple query before starting the engine

Example fix

// before
<property name="databaseSchemaUpdate" value="true"/>
// after
<!-- validate schema first with correct user privileges -->
<property name="databaseSchemaUpdate" value="false"/>
<property name="databaseSchema" value="ACT"/>

Defensive patterns

Strategy: try-catch

Validate before calling

// before engine startup
try (Connection c = dataSource.getConnection()) {
    DatabaseMetaData md = c.getMetaData();
    try (ResultSet rs = md.getTables(null, null, "ACT_%", new String[]{"TABLE"})) {
        if (!rs.isBeforeFirst()) throw new IllegalStateException("no metadata access");
    }
}

Try / catch

try {
    tableNames = tableDataManager.getTablesPresentInDatabase();
} catch (ActivitiException e) {
    logger.error("table metadata lookup failed", e.getCause());
    throw new ConfigurationException("fix DB metadata access", e);
}

Prevention

Verify DB user has catalog/metadata read privileges before startup
Set databaseSchema/catalog correctly for your database
Keep JDBC driver versions current
Set databaseSchemaUpdate=false in production after initial schema creation

When it happens

Trigger: Calling getTablesPresentInDatabase() (directly or via getTableCount / schema operations like ProcessEngine configuration with databaseSchemaUpdate) when the JDBC connection is broken, the database user lacks metadata privileges, or the catalog/schemaFilter configured does not match the database.

Common situations: Wrong databaseSchema/catalog settings in the datasource config; DB user without SELECT on metadata tables; connection dropped between pool checkout and metadata call; unsupported JDBC driver returning errors from getTables().

Understand the failure class

Background: Database query failed: Internal Server Error 500s wrapping SQL, Prisma, and connection failures — what to check first — this error's family across 16 libraries.

Related errors

AI-assisted analysis of Activiti/Activiti@56435b1a97 (2026-09-09). Data as JSON: /api/errors/18e3ae06640aea6f. Report an issue: GitHub.

Appendix: source

Thrown at activiti-core/activiti-engine/src/main/java/org/activiti/engine/impl/persistence/entity/TableDataManagerImpl.java:206

                }

                tables = databaseMetaData.getTables(
                    catalog,
                    schema,
                    tableNameFilter,
                    DbSqlSession.JDBC_METADATA_TABLE_TYPES
                );
                while (tables.next()) {
                    String tableName = tables.getString("TABLE_NAME");
                    tableName = tableName.toUpperCase();
                    tableNames.add(tableName);
                    log.debug("  retrieved activiti table name {}", tableName);
                }
            } finally {
                tables.close();
            }
        } catch (Exception e) {
            throw new ActivitiException("couldn't get activiti table names using metadata: " + e.getMessage(), e);
        }
        return tableNames;
    }

    protected long getTableCount(String tableName) {
        log.debug("selecting table count for {}", tableName);
        Long count = (Long) getDbSqlSession().selectOne("selectTableCount", singletonMap("tableName", tableName));
        return count;
    }

    @Override
    @SuppressWarnings("unchecked")
    public TablePage getTablePage(TablePageQueryImpl tablePageQuery, int firstResult, int maxResults) {
        TablePage tablePage = new TablePage();

        @SuppressWarnings("rawtypes")
        List tableData = getDbSqlSession()
            .getSqlSession()

View on GitHub (pinned to 56435b1a97)