{"record":{"id":"8a1ffc48c9c151f5","repo":"flowable/flowable-engine","slug":"datasource-or-jdbc-properties-have-to-be-specified-8a1ffc","errorCode":null,"errorMessage":"DataSource or JDBC properties have to be specified in a process engine configuration","messagePattern":"DataSource or JDBC properties have to be specified in a process engine configuration","errorType":"exception","errorClass":"ActivitiException","httpStatus":null,"severity":"critical","filePath":"modules/flowable5-engine/src/main/java/org/activiti/engine/impl/cfg/ProcessEngineConfigurationImpl.java","lineNumber":730,"sourceCode":"        if (service instanceof ServiceImpl) {\n            ((ServiceImpl) service).setCommandExecutor(commandExecutor);\n        }\n    }\n\n    // DataSource ///////////////////////////////////////////////////////////////\n\n    protected void initDataSource() {\n        if (dataSource == null) {\n            if (dataSourceJndiName != null) {\n                try {\n                    dataSource = (DataSource) new InitialContext().lookup(dataSourceJndiName);\n                } catch (Exception e) {\n                    throw new ActivitiException(\"couldn't lookup datasource from \" + dataSourceJndiName + \": \" + e.getMessage(), e);\n                }\n\n            } else if (jdbcUrl != null) {\n                if ((jdbcDriver == null) || (jdbcUsername == null)) {\n                    throw new ActivitiException(\"DataSource or JDBC properties have to be specified in a process engine configuration\");\n                }\n\n                LOGGER.debug(\"initializing datasource to db: {}\", jdbcUrl);\n\n                PooledDataSource pooledDataSource = new PooledDataSource(ReflectUtil.getClassLoader(), jdbcDriver, jdbcUrl, jdbcUsername, jdbcPassword);\n\n                if (jdbcMaxActiveConnections > 0) {\n                    pooledDataSource.setPoolMaximumActiveConnections(jdbcMaxActiveConnections);\n                }\n                if (jdbcMaxIdleConnections > 0) {\n                    pooledDataSource.setPoolMaximumIdleConnections(jdbcMaxIdleConnections);\n                }\n                if (jdbcMaxCheckoutTime > 0) {\n                    pooledDataSource.setPoolMaximumCheckoutTime(jdbcMaxCheckoutTime);\n                }\n                if (jdbcMaxWaitTime > 0) {\n                    pooledDataSource.setPoolTimeToWait(jdbcMaxWaitTime);\n                }","sourceCodeStart":712,"sourceCodeEnd":748,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable5-engine/src/main/java/org/activiti/engine/impl/cfg/ProcessEngineConfigurationImpl.java#L712-L748","documentation":"If neither dataSource nor dataSourceJndiName is set, the engine falls back to building a pooled datasource from jdbcUrl. That fallback requires jdbcDriver and jdbcUsername to also be set; if either is null, initDataSource throws this ActivitiException because a connection cannot be established.","triggerScenarios":"Configuration with jdbcUrl set but jdbcDriver or jdbcUsername left null when buildProcessEngine initializes the datasource — e.g. only setJdbcUrl called, or XML config missing the driver/username properties.","commonSituations":"Partial JDBC configuration copied from examples; switching from a container-managed datasource to JDBC properties and forgetting username; H2 in-memory setups that omit the driver class.","solutions":["Set all three: jdbcUrl, jdbcDriver (e.g. org.h2.Driver) and jdbcUsername (jdbcPassword optional) on the configuration","Or provide a ready-made DataSource via setDataSource(...) and skip JDBC properties","Or set dataSourceJndiName to a bound JNDI resource","Review your activiti.cfg.xml / Spring bean for the missing jdbcDriver or jdbcUsername property"],"exampleFix":"// before\ncfg.setJdbcUrl(\"jdbc:h2:mem:activiti\");\ncfg.buildProcessEngine(); // throws\n// after\ncfg.setJdbcUrl(\"jdbc:h2:mem:activiti\");\ncfg.setJdbcDriver(\"org.h2.Driver\");\ncfg.setJdbcUsername(\"sa\");\ncfg.setJdbcPassword(\"\");\ncfg.buildProcessEngine();","handlingStrategy":"validation","validationCode":"if (cfg.getDataSource() == null && cfg.getDataSourceJndiName() == null) {\n  if (cfg.getJdbcUrl() == null || cfg.getJdbcDriver() == null || cfg.getJdbcUsername() == null) {\n    throw new IllegalStateException(\"Set jdbcUrl + jdbcDriver + jdbcUsername, a DataSource, or a JNDI name\");\n  }\n}","typeGuard":null,"tryCatchPattern":"try {\n  processEngine = cfg.buildProcessEngine();\n} catch (ActivitiException e) {\n  if (e.getMessage().contains(\"DataSource or JDBC properties have to be specified\")) {\n    throw new ConfigurationException(\"Incomplete JDBC config: driver/username missing\", e);\n  } else throw e;\n}","preventionTips":["Set jdbcUrl, jdbcDriver and jdbcUsername together whenever using JDBC properties","Or pass a fully constructed DataSource via setDataSource","Keep activiti.cfg.xml properties in sync with documentation/examples","Add a config self-check before buildProcessEngine"],"tags":["activiti","configuration","datasource","jdbc"],"backgroundTag":"missing-required-config-field","analyzedSha":"d6d39ce1c69ff244f2d9dc6af756a9b95e865586","analyzedAt":"2026-09-11T06:41:19.413Z","contentChangedAt":"2026-09-11T06:41:19.413Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}