flowable/flowable-engine · critical · FlowableException

resource '${resourceName}' is not available

Error message

resource '${resourceName}' is not available

What it means

executeSchemaResource loads a schema SQL script from the classpath via ReflectUtil. If the resource stream is null and the script was not marked optional, it throws FlowableException stating the resource is not available. This guards against silently 'upgrading' a database while executing nothing.

Source

Thrown at modules/flowable-engine-common/src/main/java/org/flowable/common/engine/impl/db/AbstractSqlScriptBasedDbSchemaManager.java:230

    
    public String getResourceForDbOperation(String directory, String operation, String component, String databaseType) {
        return getResourcesRootDirectory() + directory + "/flowable." + databaseType + "." + operation + "." + component + ".sql";
    }
    
    protected abstract String getResourcesRootDirectory();
    
    public void executeMandatorySchemaResource(String operation, String component) {
        String databaseType = getDatabaseConfiguration().getDatabaseType();
        executeSchemaResource(operation, component, getResourceForDbOperation(operation, operation, component, databaseType), false);
    }

    public void executeSchemaResource(String operation, String component, String resourceName, boolean isOptional) {
        InputStream inputStream = null;
        try {
            inputStream = ReflectUtil.getResourceAsStream(resourceName);
            if (inputStream == null) {
                if (!isOptional) {
                    throw new FlowableException("resource '" + resourceName + "' is not available");
                }
            } else {
                executeSchemaResource(operation, component, resourceName, inputStream);
            }

        } finally {
            IoUtil.closeSilently(inputStream);
        }
    }

    protected void executeSchemaResource(String operation, String component, String resourceName, InputStream inputStream) {
        logger.info("performing {} on {} with resource {}", operation, component, resourceName);
        String sqlStatement = null;
        String exceptionSqlStatement = null;
        try {
            SchemaManagerDatabaseConfiguration databaseConfiguration = getDatabaseConfiguration();
            Connection connection = databaseConfiguration.getConnection();
            Exception exception = null;

View on GitHub (pinned to d6d39ce1c6)

Solutions

  1. Ensure all Flowable jars are the same version so every required upgrade script exists on the classpath.
  2. Check that the build/packaging does not exclude .sql resources from the jars.
  3. Upgrade through supported version steps that include the missing script, or run the missing SQL manually and update the schema version property.
  4. Inspect the resourceName in the message and confirm the file exists in the flowable-engine jar.

Example fix

// before (pom.xml, mixed versions)
<dependency><groupId>org.flowable</groupId><artifactId>flowable-engine</artifactId><version>6.6.0</version></dependency>
<dependency><groupId>org.flowable</groupId><artifactId>flowable-engine-common</artifactId><version>6.4.2</version></dependency>
// after
<dependency><groupId>org.flowable</groupId><artifactId>flowable-engine</artifactId><version>6.6.0</version></dependency>
<dependency><groupId>org.flowable</groupId><artifactId>flowable-engine-common</artifactId><version>6.6.0</version></dependency>
Defensive patterns

Strategy: validation

Validate before calling

String res = "org/flowable/db/upgrade/flowable_mysql_engine_6.5.0_to_6.6.0.sql";
if (getClass().getClassLoader().getResource(res) == null) throw new IllegalStateException("Missing schema script: " + res);

Try / catch

try { engineCfg.buildProcessEngine(); } catch (FlowableException e) { if (e.getMessage().startsWith("resource '")) { log.error("Missing schema script — check jar versions/classpath: {}", e.getMessage()); } throw e; }

Prevention

When it happens

Trigger: dbSchemaUpgrade/dbSchemaCreate attempting to execute a versioned SQL script (e.g. org/flowable/db/upgrade/xxx_engine_6.5.0_to_6.6.0.sql) that is absent from the classpath, or executeMandatorySchemaResource for a mandatory script that cannot be found.

Common situations: Mixed Flowable jar versions on the classpath (old flowable-engine without the new upgrade scripts); custom packaging (shaded/ fat jars) that excluded SQL resources; upgrading across versions where an intermediate script does not exist; wrong database type mapping leading to a script path that was never shipped.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

AI-assisted analysis of flowable/flowable-engine@d6d39ce1c6 (2026-09-11). Data as JSON: /api/errors/b701114f5afe9a67. Report an issue: GitHub.