eclipse-vertx/vert.x · error · IllegalStateException
Resource manager shutdown
Error message
Resource manager shutdown
What it means
ResourceManager tracks its lifecycle with a status counter; checkStatus() rejects any operation once the manager has been shut down (status 1). withResource() (and other entry points) therefore throws this IllegalStateException when a resource is requested after shutdown() was called. Shutdown only rejects new requests; it does not mean the manager was used incorrectly, only that it is no longer accepting work.
Source
Thrown at vertx-core/src/main/java/io/vertx/core/internal/resource/ResourceManager.java:110
/**
* Get a resource resolved by {@code key}
*
* @param key the resource key
* @return the future resolved with the resource
*/
public <T> Future<T> withResourceAsync(K key, Function<K, R> provider, BiFunction<R, Boolean, Future<T>> function) {
return withResource(key, provider, Function.identity(), (res, created) -> {
if (res.before()) {
return function.apply(res, created).andThen(ar -> res.after());
}
return null;
});
}
private void checkStatus() {
int st = status.get();
if (st == 1) {
throw new IllegalStateException("Resource manager shutdown");
} else if (st == 2) {
throw new IllegalStateException("Resource manager closed");
}
}
/**
* Shutdown the resource manager: any new request will be rejected.
*/
public void shutdown() {
if (status.compareAndSet(0, 1)) {
for (ManagedResource resource : resources.values()) {
resource.shutdown();
}
status.set(2);
}
}
/**View on GitHub (pinned to fb308bd8c3)
Solutions
- Ensure all work using the manager completes before calling shutdown(); await completion of in-flight operations (futures) prior to close
- Do not reuse a closed Vertx instance or closed client; create a new Vertx/client instance after close
- Guard submissions with a lifecycle check (isShutdown flag) and skip/requeue instead of calling withResource after shutdown
- Catch IllegalStateException from withResource and treat it as 'shutting down' — abort the operation gracefully rather than retrying
Example fix
// before vertx.close(); client.request() // later background task -> IllegalStateException: Resource manager shutdown // after requestFuture.compose(ok -> vertx.close()); // close only after work completes
Defensive patterns
Strategy: try-catch
Validate before calling
// track shutdown state of the owning Vertx/client before submitting work
if (vertxIsClosed || manager.isShutdown()) { // e.g. skip or requeue
return Future.failedFuture(new CancellationException("shutting down"));
} Try / catch
try {
return manager.withResource(key, supplier);
} catch (IllegalStateException e) {
if ("Resource manager shutdown".equals(e.getMessage())) {
return Future.failedFuture(new CancellationException("resource manager shutdown, operation aborted"));
}
throw e;
} Prevention
- Sequence shutdown() after all in-flight work completes (compose work futures with the close call)
- Never share a Vertx/client across components that close it independently; use reference counting or DI lifecycle hooks
- Cancel schedulers and background tasks before shutdown
- Do not retry operations that fail with this error — the manager will never accept work again
When it happens
Trigger: Calling withResource (or acquiring a resource) after ResourceManager.shutdown() has been invoked — e.g. a Vertx instance/Context was closed while background code still submits work, a connection provider's resource manager was shut down on close, or a race where a task queued before shutdown runs after it.
Common situations: Closing a Vertx instance (vertx.close()) while in-flight requests still try to create connections; using a shared/cached client whose underlying manager was closed; tests that close the Vertx context in @AfterEach while async assertions still run.
Understand the failure class
Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.
Related errors
AI-assisted analysis of eclipse-vertx/vert.x@fb308bd8c3 (2026-09-06).
Data as JSON: /api/errors/1c1cbb7ab0daf5e2.
Report an issue: GitHub.