quarkusio/quarkus · error · IllegalStateException

Dev services cannot be started without a deployment class lo

Error message

Dev services cannot be started without a deployment class loader.

What it means

StartupActionImpl.ensureDevServicesStarted() starts Dev Services (automatic containers for databases, brokers, etc.) during dev/test runs. Dev Services must run inside the deployment class loader; if it is null the framework cannot proceed and throws this error instead of failing opaquely later.

Source

Thrown at core/deployment/src/main/java/io/quarkus/runner/bootstrap/StartupActionImpl.java:340

                URL url = resources.nextElement();
                if (url.toString().contains(STARTUP_OVERRIDE.getName())) {
                    writeTempApplicationProperties(url.toURI(), config, STARTUP_OVERRIDE);
                    break;
                }
            }
        } catch (IOException | URISyntaxException e) {
            throw new RuntimeException(e);
        }
    }

    private void ensureDevServicesStarted() {
        if (devServicesStarted) {
            return;
        }
        devServicesStarted = true;
        if (devServicesRegistry != null) {
            if (deploymentClassLoader == null) {
                throw new IllegalStateException("Dev services cannot be started without a deployment class loader.");
            }
            DevServicesRegistryBuildItem.DevServicesStartResult startResult = devServicesRegistry.startAll(
                    devServicesResults, devServicesCustomizers, additionalConfigBuildItems, deploymentClassLoader);

            devServicesProperties.putAll(startResult.configs());
            setDevServicesConfigSourceValues(startResult);
        }
    }

    private void setDevServicesConfigSourceValues(DevServicesRegistryBuildItem.DevServicesStartResult startResult) {
        try {
            Class<?> configSourceClass = runtimeClassLoader
                    .loadClass("io.quarkus.devservice.runtime.config.DevServicesConfigSource");
            configSourceClass.getMethod("setConfig", Map.class).invoke(null, startResult.configs());
        } catch (ClassNotFoundException e) {
            // devservices runtime module not available
        } catch (ReflectiveOperationException e) {
            throw new RuntimeException("Failed to set dev services config", e);

View on GitHub (pinned to e1c734241f)

Solutions

1. Obtain the StartupAction via AugmentAction.createInitialRuntimeApplication() so the deployment class loader is established
2. Keep the deployment class loader open for the lifetime of dev-mode runs; do not close it before starting dev services
3. If Dev Services are not needed, disable them (quarkus.devservices.enabled=false) to skip this path
4. Re-run the dev bootstrap from scratch if the loader was already closed

// before invoking dev-mode run paths
boolean devServicesEnabled = Boolean.parseBoolean(config.get("quarkus.devservices.enabled", "true"));
if (devServicesEnabled && deploymentClassLoader == null) {
    throw new IllegalStateException("Dev services require a deployment class loader; use createInitialRuntimeApplication()");
}

try { startupAction.run(); } catch (IllegalStateException e) { if (e.getMessage().contains("deployment class loader")) { /* recreate StartupAction via augment action */ } else { throw e; } }

When it happens

Trigger: Calling run(), runMainClass(), runMainClassBlocking(), or the Dev Services property accessors (getOrInitialiseDevServicesProperties/NetworkId) on a StartupActionImpl whose deployment class loader was never set — e.g. a StartupAction created without a deployment classpath or after its loader was released.

Common situations: Embedded/bootstrapped Quarkus launches in dev mode where the deployment class loader was not created; calling StartupAction APIs after the deployment class loader was closed; misconfigured custom test harnesses.

Related errors

• Failed to load steps from %s
• Dev services for ${request.getName()} requires a startable s
• name cannot be null
• The class (${name}) cannot be created during deployment.
• The class (${name}) cannot be created during deployment.

AI-assisted analysis of quarkusio/quarkus@e1c734241f (2026-09-05). Data as JSON: /api/errors/7463f1d9a93cc558. Report an issue: GitHub.