karatelabs/karate · error · IllegalStateException

cannot reset while shutting down

Error message

cannot reset while shutting down

What it means

KarateLifecycle.reset() restores the singleton lifecycle to its initial RUNNING state (clearing results and registrations). It refuses to run when the lifecycle is currently in the SHUTTING_DOWN phase, throwing IllegalStateException — resetting mid-shutdown would resurrect state that a concurrent shutdown is actively tearing down.

Solutions

1. Ensure reset() is called before shutdown begins or after it fully completes — sequence your fixture teardown accordingly
2. Check lifecycle state before resetting (isShutdown in progress / current phase) and skip reset if shutting down
3. Move reset() out of shutdown hooks and into explicit pre-run setup
4. Serialize suite lifecycle: wait for the previous run's shutdown to finish before resetting

Example fix

// before
// in @AfterAll / shutdown hook
KarateLifecycle.reset();
// after
if (!KarateLifecycle.isShutdownInProgress()) { // guard against SHUTTING_DOWN phase
    KarateLifecycle.reset();
}

// Java: check shutdown state before resetting
// if lifecycle exposes phase/state, only reset when not shutting down
if (!lifecycle.isShutdownInProgress()) {
    KarateLifecycle.reset();
}

try {
    KarateLifecycle.reset();
} catch (IllegalStateException e) {
    if (!e.getMessage().contains("cannot reset while shutting down")) throw e;
    // skip or defer reset until after shutdown completes
}

When it happens

Trigger: Calling KarateLifecycle.reset() from a hook, test listener, or parallel thread while a shutdown is in flight (e.g. JVM shutdown hook executing, or after Karate.run() completion while shutdown runs); a test-fixture @AfterAll racing with the framework's own shutdown.

Common situations: Custom test runners that call reset() in cleanup code; reusing the same JVM across suite runs where cleanup hooks overlap; parallel test suites where one suite's shutdown coincides with another's reset.

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

• Provider has been shut down
• registered while , stopping immediately
• shutdown in progress failed
• karate.driver can only be read within a scenario
• channel() can only be called within a scenario

AI-assisted analysis of karatelabs/karate@a22eb90246 (2026-09-12). Data as JSON: /api/errors/320125dc3bf018e7. Report an issue: GitHub.

Appendix: source

Thrown at karate-js/src/main/java/io/karatelabs/common/KarateLifecycle.java:227

    /** Where the register currently is — see {@link Phase}. */
    public static Phase phase() {
        synchronized (LOCK) {
            return phase;
        }
    }

    /**
     * Return the register to {@link Phase#RUNNING} so it accepts registrations again. Meant for
     * tests, and for an application that deliberately restarts Karate inside a live JVM; a normal
     * shutdown never needs it. Anything left over from the previous life is dropped, not stopped.
     *
     * @throws IllegalStateException if a shutdown is in flight
     */
    public static void reset() {
        synchronized (LOCK) {
            if (phase == Phase.SHUTTING_DOWN) {
                throw new IllegalStateException("cannot reset while shutting down");
            }
            phase = Phase.RUNNING;
            results = List.of();
        }
        synchronized (REGISTERED) {
            REGISTERED.clear();
        }
    }

    /**
     * Stop everything registered, in reverse registration order, bounded by
     * {@link #DEFAULT_TIMEOUT}.
     */
    public static List<StopResult> shutdownAll() {
        return shutdownAll(DEFAULT_TIMEOUT);
    }

    /**

View on GitHub (pinned to a22eb90246)