{"record":{"id":"8ab7a955f1c880cf","repo":"flowable/flowable-engine","slug":"activiti-database-problem-errormessage","errorCode":null,"errorMessage":"Activiti database problem: <errorMessage>","messagePattern":"Activiti database problem: <errorMessage>","errorType":"exception","errorClass":"ActivitiException","httpStatus":null,"severity":"error","filePath":"modules/flowable5-engine/src/main/java/org/activiti/engine/impl/db/DbSqlSession.java","lineNumber":941,"sourceCode":"    // schema operations ////////////////////////////////////////////////////////\n\n    public void dbSchemaCheckVersion() {\n        try {\n            String dbVersion = getDbVersion();\n            if (!ProcessEngine.VERSION.equals(dbVersion)) {\n                throw new ActivitiWrongDbException(ProcessEngine.VERSION, dbVersion);\n            }\n\n            String errorMessage = null;\n            if (!isEngineTablePresent()) {\n                errorMessage = addMissingComponent(errorMessage, \"engine\");\n            }\n            if (dbSqlSessionFactory.isDbHistoryUsed() && !isHistoryTablePresent()) {\n                errorMessage = addMissingComponent(errorMessage, \"history\");\n            }\n\n            if (errorMessage != null) {\n                throw new ActivitiException(\"Activiti database problem: \" + errorMessage);\n            }\n\n        } catch (Exception e) {\n            if (isMissingTablesException(e)) {\n                throw new ActivitiException(\n                        \"no activiti tables in db. set <property name=\\\"databaseSchemaUpdate\\\" to value=\\\"true\\\" or value=\\\"create-drop\\\" (use create-drop for testing only!) in bean processEngineConfiguration in flowable.cfg.xml for automatic schema creation\",\n                        e);\n            } else {\n                if (e instanceof RuntimeException) {\n                    throw (RuntimeException) e;\n                } else {\n                    throw new ActivitiException(\"couldn't get db schema version\", e);\n                }\n            }\n        }\n\n        LOGGER.debug(\"activiti db schema check successful\");\n    }","sourceCodeStart":923,"sourceCodeEnd":959,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable5-engine/src/main/java/org/activiti/engine/impl/db/DbSqlSession.java#L923-L959","documentation":"dbSchemaCheckVersion() builds an errorMessage listing required schema components (engine, history, etc.) whose tables are missing via addMissingComponent(); if any are absent it throws this ActivitiException. It means the connected database exists but is missing required Activiti/Flowable tables for the components the configuration uses.","triggerScenarios":"databaseSchemaUpdate=false (or 'false' variant that only checks) while connecting to an empty or partially initialized schema; dbSqlSessionFactory.isDbHistoryUsed() is true but history tables were dropped; a partial manual schema creation.","commonSituations":"Fresh database with schema creation disabled; someone dropped ACT_* tables (e.g. history cleanup gone wrong); wrong JDBC URL pointing at an empty schema; DB user lacking SELECT on the tables so presence checks fail.","solutions":["Set <property name=\"databaseSchemaUpdate\" value=\"true\"/> in flowable.cfg.xml so missing tables are created at startup (create-drop for tests only).","Run the DB-specific create scripts from the engine distribution to create the missing ACT_* tables manually.","Check the JDBC URL/credentials point at the correct schema, and confirm the DB user can see the tables (grants).","If history is intentionally unused, disable it (dbHistoryUsed / historyLevel none) so the history table check is skipped."],"exampleFix":"// before: empty DB, check-only\n<property name=\"databaseSchemaUpdate\" value=\"false\"/>\n\n// after: let engine create missing tables\n<property name=\"databaseSchemaUpdate\" value=\"true\"/>","handlingStrategy":"validation","validationCode":"// Check required tables exist before engine startup\nfor (String t : new String[]{\"ACT_GE_PROPERTY\", \"ACT_RU_EXECUTION\", \"ACT_HI_PROCINST\"}) {\n    Integer n = jdbcTemplate.queryForObject(\n        \"SELECT COUNT(*) FROM information_schema.tables WHERE table_name = ?\", Integer.class, t);\n    if (n == null || n == 0) throw new IllegalStateException(\"Missing table \" + t + \" — enable databaseSchemaUpdate\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    ProcessEngines.buildProcessEngine();\n} catch (ActivitiException e) {\n    if (e.getMessage().startsWith(\"Activiti database problem\")) {\n        log.error(\"Missing Activiti tables: {}\", e.getMessage());\n    }\n    throw e;\n}","preventionTips":["Use databaseSchemaUpdate=true on first boot in each environment, then switch to false after schema is stable.","Never drop ACT_* tables (especially history) without also disabling history usage in config.","Verify JDBC URL and grants point to the schema that actually contains the tables."],"tags":["database","schema","missing-tables","startup"],"backgroundTag":"database-table-missing","analyzedSha":"d6d39ce1c69ff244f2d9dc6af756a9b95e865586","analyzedAt":"2026-09-11T06:41:19.413Z","contentChangedAt":"2026-09-11T06:41:19.413Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}