{"record":{"id":"5e3af6cc2e6a46fb","repo":"flowable/flowable-engine","slug":"flowable-idm-database-problem-errormessage","errorCode":null,"errorMessage":"Flowable IDM database problem: ${errorMessage}","messagePattern":"Flowable IDM database problem: (.+?)","errorType":"console","errorClass":"FlowableException","httpStatus":null,"severity":"critical","filePath":"modules/flowable-idm-engine/src/main/java/org/flowable/idm/engine/impl/db/IdmDbSchemaManager.java","lineNumber":84,"sourceCode":"   public boolean isIdmGroupTablePresent() {\n       return isTablePresent(\"ACT_ID_GROUP\");\n   }\n   \n   @Override\n   public void schemaCheckVersion() {\n       try {\n           String dbVersion = getSchemaVersion();\n           if (!IdmEngine.VERSION.equals(dbVersion)) {\n               throw new FlowableWrongDbException(IdmEngine.VERSION, dbVersion);\n           }\n\n           String errorMessage = null;\n           if (!isTablePresent(IDM_PROPERTY_TABLE)) {\n               errorMessage = addMissingComponent(errorMessage, \"engine\");\n           }\n\n           if (errorMessage != null) {\n               throw new FlowableException(\"Flowable IDM 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 idm db schema check successful\");\n   }","sourceCodeStart":66,"sourceCodeEnd":102,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-idm-engine/src/main/java/org/flowable/idm/engine/impl/db/IdmDbSchemaManager.java#L66-L102","documentation":"Thrown by the IDM engine's schema version check when the required Flowable IDM database tables are absent or the schema is incompatible. It aggregates which components are missing (e.g. 'engine') into the message. Flowable validates the DB schema at engine bootstrap so it fails fast instead of failing later at runtime.","triggerScenarios":"Calling ProcessEngine/IdmEngine bootstrap with databaseSchemaUpdate=false (default) against a database that has no IDM tables (no ACT_ID_PROPERTY table), or a schema from an incompatible Flowable version.","commonSituations":"Fresh deployment pointing at an empty database; switching databases without re-running schema creation; a JDBC user without rights to read the tables; upgrading Flowable against an old schema.","solutions":["Set databaseSchemaUpdate=true (or create-drop for testing) in processEngineConfiguration in flowable.cfg.xml so tables are created automatically.","Manually run the Flowable SQL scripts (org/flowable/idm/db/create/*.sql) for your database against the target schema.","Verify the datasource points at the database where the ACT_ID_* tables actually exist and that the user has SELECT rights.","Check schema version compatibility between the Flowable version and the DB (ACT_ID_PROPERTY schema.version)."],"exampleFix":"// before (flowable.cfg.xml)\n<property name=\"databaseSchemaUpdate\" value=\"false\" />\n// after\n<property name=\"databaseSchemaUpdate\" value=\"true\" />","handlingStrategy":"validation","validationCode":"try (Connection c = dataSource.getConnection()) {\n  DatabaseMetaData md = c.getMetaData();\n  try (ResultSet rs = md.getTables(null, null, \"ACT_ID_PROPERTY\", null)) {\n    if (!rs.next()) throw new IllegalStateException(\"Flowable IDM tables missing — run schema create or set databaseSchemaUpdate=true\");\n  }\n}","typeGuard":null,"tryCatchPattern":"try {\n  idmEngine = config.buildEngine();\n} catch (FlowableException e) {\n  if (e.getMessage().contains(\"database problem\")) {\n    // run schema creation scripts or enable databaseSchemaUpdate, then retry\n  }\n  throw e;\n}","preventionTips":["Set databaseSchemaUpdate=true in non-production environments.","Keep DB migrations in the deploy pipeline when schema update is disabled in production.","Add a startup health check that verifies ACT_ID_* tables exist.","Use the same datasource for engine and manual SQL scripts."],"tags":["database","schema","bootstrap","flowable"],"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"}