flowable/flowable-engine · warning

FileInstall package is not available, disabling fileinstall…

Error message

FileInstall package is not available, disabling fileinstall support

What it means

The Flowable OSGi activator registers Bpmn/Bar deployment listeners that rely on the FileInstall API package. If FileInstall classes are absent from the OSGi runtime, a NoClassDefFoundError is caught and fileinstall auto-deployment support is disabled with this warning. The bundle still starts; only automatic deployment of BPMN/BAR artifacts dropped into watched folders is skipped.

Solutions

1. Install the Apache Felix FileInstall bundle (org.apache.felix.fileinstall) into the OSGi container and start it before flowable-osgi.
2. Verify flowable-osgi's Import-Package for org.apache.felix.fileinstall resolves (check bundle:wiring / diag in Karaf).
3. If FileInstall support is not needed, ignore the warning; deploy process definitions programmatically via RepositoryService instead.
4. Bump to a Flowable version whose flowable-osgi manifest matches your FileInstall version.

Example fix

// before (no FileInstall bundle installed)
osgi> install flowable-osgi
// warning: FileInstall package is not available...
// after
osgi> feature:install fileinstall
osgi> start flowable-osgi // listeners registered

Bundle fileInstall = context.getBundleByName("org.apache.felix.fileinstall");
if (fileInstall == null || fileInstall.getState() != Bundle.ACTIVE) {
    logger.info("FileInstall absent; deploy via RepositoryService programmatically");
}

static boolean fileInstallAvailable(BundleContext ctx) {
    try {
        Class.forName("org.apache.felix.fileinstall.ArtifactListener");
        return true;
    } catch (ClassNotFoundException e) { return false; }
}

When it happens

Trigger: BundleContext start of org.flowable.osgi.Activator when callbacks.add(new Service(..., BpmnDeploymentListener/BarDeploymentListener ...)) throws NoClassDefFoundError because org.apache.felix.fileinstall.ArtifactUrlTransformer or ArtifactListener is not resolvable.

Common situations: Deploying the flowable-osgi bundle into a Karaf/Equinox container without the Apache Felix FileInstall bundle installed or without its package exported/imported in the manifest; OSGi Import-Package resolution marked optional and FileInstall missing.

Understand the failure class

Background: "X is not installed. Please install it with pip install Y": missing optional dependency errors — ImportError/ValueError raised when a library's optional extra was never installed — this error's family across 22 libraries.

Related errors

• Error opening url:
• Bundle cannot be generated
• byte array for resource
• byte array for resource
• byte array for resource

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

Appendix: source

Thrown at modules/flowable-osgi/src/main/java/org/flowable/osgi/Activator.java:48

 * OSGi Activator
 *
 * @author <a href="gnodet@gmail.com">Guillaume Nodet</a>
 */
public class Activator implements BundleActivator {

    private static final Logger LOGGER = LoggerFactory.getLogger(Activator.class);

    private List<Runnable> callbacks = new ArrayList<>();

    @Override
    public void start(BundleContext context) throws Exception {
        callbacks.add(new Service(context, URLStreamHandlerService.class.getName(), new BpmnURLHandler(), props("url.handler.protocol", "bpmn")));
        callbacks.add(new Service(context, URLStreamHandlerService.class.getName(), new BarURLHandler(), props("url.handler.protocol", "bar")));
        try {
            callbacks.add(new Service(context, new String[]{ArtifactUrlTransformer.class.getName(), ArtifactListener.class.getName()}, new BpmnDeploymentListener(), null));
            callbacks.add(new Service(context, new String[]{ArtifactUrlTransformer.class.getName(), ArtifactListener.class.getName()}, new BarDeploymentListener(), null));
        } catch (NoClassDefFoundError e) {
            LOGGER.warn("FileInstall package is not available, disabling fileinstall support");
            LOGGER.debug("FileInstall package is not available, disabling fileinstall support", e);
        }
        callbacks.add(new Tracker(new Extender(context)));
    }

    @Override
    public void stop(BundleContext context) throws Exception {
        for (Runnable r : callbacks) {
            r.run();
        }
    }

    private static Dictionary<String, String> props(String... args) {
        Dictionary<String, String> props = new Hashtable<>();
        for (int i = 0; i < args.length / 2; i++) {
            props.put(args[2 * i], args[2 * i + 1]);
        }
        return props;

View on GitHub (pinned to d6d39ce1c6)