flowable/flowable-engine · error · IllegalStateException

Failed to load property source from location

Error message

Failed to load property source from location '${location}'

What it means

FlowableDefaultPropertiesEnvironmentPostProcessor loads flowable default properties (e.g. from the configured location) into the Spring Environment before context refresh. If loading the resource throws any exception, it is wrapped in this IllegalStateException naming the location. It almost always wraps an underlying cause (unreadable resource, malformed properties, classpath issue).

Solutions

1. Read the wrapped cause in the stack trace — it names the actual loading problem
2. Verify the resource at the configured location exists, is readable, and parses as valid .properties/.yml
3. Check the location format in flowable configuration (classpath: vs file: prefix)
4. Rebuild/repackage the artifact so the resource is actually present in the jar

Example fix

// before: wrong location
flowable.default-properties-location=file:application-flowable.prop
// after: correct extension and prefix
flowable.default-properties-location=classpath:application-flowable.properties

URL res = getClass().getResource("/application-flowable.properties");
if (res == null) throw new IllegalStateException("flowable properties resource missing");
new Properties().load(res.openStream()); // fails fast with a clear error

boolean loadable = resource != null && resource.isReadable();

try { environmentPostProcessor.load(loc, res); } catch (IllegalStateException e) { logger.error("cause: {}", e.getCause(), e); }

When it happens

Trigger: EnvironmentPostProcessor.load(location) resolves a resource that exists but cannot be loaded: InvalidPropertiesFormatException, IOException, classpath mismatch, or a custom PropertySourceLoader failure while loading propertyResourceName from that resource.

Common situations: Corrupt or non-UTF-8 properties/YAML file at the flowable default-properties location; a file specified with the wrong protocol prefix; packaged resource missing from the jar after repackaging; security manager or read permission blocking the resource.

Understand the failure class

Background: "failed to read file", EACCES, ENOENT and "could not read <path>" errors: when a program can't read a file from disk — this error's family across 49 libraries.

Related errors

• BPMN engine has not been initialized
• Cannot read EL properties
• Class has not been found.
• CMMN engine has not been initialized
• Could not load image for decision requirements diagram…

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

Appendix: source

Thrown at modules/flowable-spring-boot/flowable-spring-boot-starters/flowable-spring-boot-autoconfigure/src/main/java/org/flowable/spring/boot/environment/FlowableDefaultPropertiesEnvironmentPostProcessor.java:90

            }

        }

        void load(String location, PropertySourceLoader loader) {
            try {
                Resource resource = resourceLoader.getResource(location);
                if (!resource.exists()) {
                    return;
                }
                String propertyResourceName = "flowableDefaultConfig: [" + location + "]";

                List<PropertySource<?>> propertySources = loader.load(propertyResourceName, resource);
                if (propertySources == null) {
                    return;
                }
                propertySources.forEach(source -> environment.getPropertySources().addLast(source));
            } catch (Exception ex) {
                throw new IllegalStateException("Failed to load property "
                    + "source from location '" + location + "'", ex);
            }
        }
    }
}

View on GitHub (pinned to d6d39ce1c6)