{"record":{"id":"08c1c3915b577b75","repo":"flowable/flowable-engine","slug":"unable-to-find-a-processengine-service","errorCode":null,"errorMessage":"Unable to find a ProcessEngine service","messagePattern":"Unable to find a ProcessEngine service","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"modules/flowable-osgi/src/main/java/org/flowable/osgi/Extender.java","lineNumber":212,"sourceCode":"                        filePattern = name;\n                    } else {\n                        baseName = name.substring(0, pos + 1);\n                        filePattern = name.substring(pos + 1);\n                    }\n                    if (hasWildcards(filePattern)) {\n                        addEntries(bundle, baseName, filePattern, pathList);\n                    } else {\n                        addEntry(bundle, name, pathList);\n                    }\n                }\n            }\n\n            if (!pathList.isEmpty()) {\n                LOGGER.debug(\"Found flowable process in bundle {} with paths: {}\", bundle.getSymbolicName(), pathList);\n\n                ProcessEngine engine = (ProcessEngine) engineServiceTracker.waitForService(timeout);\n                if (engine == null) {\n                    throw new IllegalStateException(\"Unable to find a ProcessEngine service\");\n                }\n\n                RepositoryService service = engine.getRepositoryService();\n                DeploymentBuilder builder = service.createDeployment();\n                builder.name(bundle.getSymbolicName());\n                for (URL url : pathList) {\n                    InputStream is = url.openStream();\n                    if (is == null) {\n                        throw new IOException(\"Error opening url: \" + url);\n                    }\n                    try {\n                        builder.addInputStream(getPath(url), is);\n                    } finally {\n                        is.close();\n                    }\n                }\n                builder.enableDuplicateFiltering();\n                builder.deploy();","sourceCodeStart":194,"sourceCodeEnd":230,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-osgi/src/main/java/org/flowable/osgi/Extender.java#L194-L230","documentation":"During OSGi bundle processing, Extender.checkBundle waits (up to a configured timeout) for a ProcessEngine to be registered as an OSGi service. If the service tracker times out or returns null, it throws IllegalStateException because deploying the bundle's processes is impossible without an engine. This indicates the Flowable engine was not started or not exported as a service in the OSGi container.","triggerScenarios":"A bundle containing BPMN/BAR resources is started (via bundleChanged or at container startup via checkInitialBundle) while no ProcessEngine OSGi service is registered, or the engine registers later than the timeout passed to engineServiceTracker.waitForService(timeout).","commonSituations":"Flowable engine bundle not started before process bundles; engine failed to initialize (bad database config) so its service never registered; timeout too short for slow container startup; engine registered with wrong service properties so the tracker filter doesn't match.","solutions":["Ensure the Flowable ProcessEngine (e.g. flowable-osgi / engine bundle) is started before the process-containing bundle","Check engine startup logs for initialization failure (database, config)","Increase the Extender timeout configuration if the engine starts slowly","Verify the ProcessEngine is registered as an OSGi service with the properties the service tracker filters on"],"exampleFix":"// before\n// process bundle started while engine bundle still in STARTING\n// after\n// in the process bundle activator, require the engine first:\nServiceReference<?> ref = context.getServiceReference(ProcessEngine.class);\nif (ref == null) { throw new BundleException(\"ProcessEngine service not available; start the Flowable engine bundle first\"); }","handlingStrategy":"validation","validationCode":"BundleContext ctx = ...;\nServiceReference<ProcessEngine> ref = ctx.getServiceReference(ProcessEngine.class);\nif (ref == null) {\n    throw new IllegalStateException(\"Flowable ProcessEngine OSGi service not registered; start the engine bundle before process bundles\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    extenderCheckBundle();\n} catch (IllegalStateException e) {\n    if (e.getMessage().contains(\"ProcessEngine\")) {\n        logger.error(\"ProcessEngine service unavailable — verify engine bundle is ACTIVE and registered\", e);\n    }\n    throw e;\n}","preventionTips":["Set correct start levels so the engine bundle starts before process bundles","Monitor engine initialization logs for database/config failures that prevent service registration","Tune the Extender service-tracker timeout to your container's startup speed"],"tags":["osgi","process-engine","lifecycle"],"backgroundTag":"missing-dependency","analyzedSha":"d6d39ce1c69ff244f2d9dc6af756a9b95e865586","analyzedAt":"2026-09-11T06:41:19.413Z","contentChangedAt":"2026-09-11T06:41:19.413Z","schemaVersion":2},"datasetVersion":"2026-09-18T11:17:12.947Z"}