{"record":{"id":"967b872027b13d2e","repo":"flowable/flowable-engine","slug":"flowable-database-problem-errormessage-967b87","errorCode":null,"errorMessage":"Flowable database problem: ${errorMessage}","messagePattern":"Flowable database problem: (.+?)","errorType":"exception","errorClass":"FlowableException","httpStatus":null,"severity":"critical","filePath":"modules/flowable-engine/src/main/java/org/flowable/engine/impl/db/ProcessDbSchemaManager.java","lineNumber":53,"sourceCode":"    \n    @Override\n    public void schemaCheckVersion() {\n        try {\n            String dbVersion = getDbVersion();\n            if (!ProcessEngine.VERSION.equals(dbVersion)) {\n                throw new FlowableWrongDbException(ProcessEngine.VERSION, dbVersion);\n            }\n\n            String errorMessage = null;\n            if (!isEngineTablePresent()) {\n                errorMessage = addMissingComponent(errorMessage, \"engine\");\n            }\n            if (CommandContextUtil.getDbSqlSession().getDbSqlSessionFactory().isDbHistoryUsed() && !isHistoryTablePresent()) {\n                errorMessage = addMissingComponent(errorMessage, \"history\");\n            }\n\n            if (errorMessage != null) {\n                throw new FlowableException(\"Flowable database problem: \" + errorMessage);\n            }\n\n        } catch (Exception e) {\n            if (isMissingTablesException(e)) {\n                throw new FlowableException(\n                        \"no flowable 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 FlowableException(\"couldn't get db schema version\", e);\n                }\n            }\n        }\n\n        logger.debug(\"flowable db schema check successful\");\n    }","sourceCodeStart":35,"sourceCodeEnd":71,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-engine/src/main/java/org/flowable/engine/impl/db/ProcessDbSchemaManager.java#L35-L71","documentation":"Thrown during schemaCheckVersion when one or more expected Flowable table groups (engine, history, and optionally others) are missing from the database; the missing components are accumulated in errorMessage and reported together. It signals an incomplete or partially-created Flowable schema.","triggerScenarios":"Database exists with some Flowable tables but is missing ACT_RE_* / ACT_RU_* / ACT_HI_* groups, e.g. a partial manual schema install, a failed create, or isDbHistoryUsed=true while history tables were never created.","commonSituations":"Manually running only a subset of DDL scripts; restoring a partial backup; dropping history tables to reclaim space while dbHistoryUsed remains true; schema creation interrupted mid-run.","solutions":["Set databaseSchemaUpdate=true (or 'create-drop' in test) so the engine creates the missing tables, then restart.","Apply the complete DDL for your database from the engine's create scripts for the exact engine version.","If history tables were intentionally removed, configure dbHistoryUsed=false / historyLevel=none so the check does not require them."],"exampleFix":"// before\n<property name=\"databaseSchemaUpdate\" value=\"false\"/> <!-- history tables absent -->\n// after\n<property name=\"databaseSchemaUpdate\" value=\"true\"/> <!-- creates missing tables -->\n<!-- or: <property name=\"dbHistoryUsed\" value=\"false\"/> -->","handlingStrategy":"validation","validationCode":"boolean engineTables = managementService.getProperties().containsKey(\"schema.version\"); boolean historyTables = /* check ACT_HI_PROCINST exists via jdbc metadata */; if (!engineTables || !historyTables) { cfg.setDatabaseSchemaUpdate(\"true\"); }","typeGuard":null,"tryCatchPattern":"try { engine = cfg.buildProcessEngine(); } catch (FlowableException e) { if (e.getMessage().startsWith(\"Flowable database problem:\")) { /* create missing tables */ } }","preventionTips":["Create the schema only via official full DDL scripts or databaseSchemaUpdate=true","Check history tables exist whenever dbHistoryUsed is true","Verify restores/backups include the complete Flowable table set"],"tags":["database","schema","missing-tables"],"backgroundTag":"schema-validation-failed","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"}