jenkinsci/jenkins · warning · RestartNotSupportedException

Failed to install embedded lifecycle implementation, so cann

Error message

Failed to install embedded lifecycle implementation, so cannot restart: {t}

What it means

Thrown by an anonymous fallback Lifecycle when instantiation of UnixLifecycle failed (caught a Throwable t). The UnixLifecycle constructor typically fails when it cannot locate the jenkins.war or determine the executable path needed for exec-based restart. verifyRestartable() wraps the original cause t into the message, so the root reason is embedded in the string.

Source

Thrown at core/src/main/java/hudson/lifecycle/Lifecycle.java:128

                                    "Default Windows lifecycle does not support restart.");
                        }
                    };
                } else if (System.getenv("SMF_FMRI") != null && System.getenv("SMF_RESTARTER") != null) {
                    // when we are run by Solaris SMF, these environment variables are set.
                    instance = new SolarisSMFLifecycle();
                } else if (System.getenv("NOTIFY_SOCKET") != null) {
                    // When we are running under systemd with Type=notify, this environment variable is set.
                    instance = new SystemdLifecycle();
                } else {
                    // if run on Unix, we can do restart
                    try {
                        instance = new UnixLifecycle();
                    } catch (final Throwable t) {
                        LOGGER.log(Level.WARNING, "Failed to install embedded lifecycle implementation", t);
                        instance = new Lifecycle() {
                            @Override
                            public void verifyRestartable() throws RestartNotSupportedException {
                                throw new RestartNotSupportedException(
                                        "Failed to install embedded lifecycle implementation, so cannot restart: " + t, t);
                            }
                        };
                    }
                }
            }
            assert instance != null;
            INSTANCE = instance;
        }

        return INSTANCE;
    }

    /**
     * If the location of {@code jenkins.war} is known in this life cycle,
     * return it location. Otherwise return null to indicate that it is unknown.
     *
     * <p>

View on GitHub (pinned to 2e228ff40b)

Solutions

Check the Jenkins log for the WARNING 'Failed to install embedded lifecycle implementation' — the attached Throwable t is the real cause
Ensure the process was launched with a resolvable jenkins.war path (avoid unpacking the war in a temp dir that gets cleaned)
Use an external process manager (systemd, SMF) so Lifecycle picks SystemdLifecycle/SolarisSMFLifecycle instead of UnixLifecycle
If the war location is custom, set the relevant system property or ensure getHudsonWar() can resolve it

Defensive patterns

Strategy: try-catch

Try / catch

try {
    Lifecycle.get().verifyRestartable();
} catch (RestartNotSupportedException e) {
    // the cause (Throwable t) is attached; inspect e.getCause() for the real UnixLifecycle failure
    LOGGER.log(Level.WARNING, "Restart unavailable: " + e.getMessage(), e.getCause());
}

Prevention

Monitor Jenkins logs for the 'Failed to install embedded lifecycle implementation' WARNING at startup
Ensure jenkins.war is launched from a stable, resolvable path
Prefer systemd or SMF on Unix so the robust lifecycle is selected

When it happens

Trigger: Lifecycle.get() attempts new UnixLifecycle() on a non-Windows, non-SMF, non-systemd Unix host; the constructor throws (e.g. cannot resolve the launch command or the war file). The catch(Throwable) block logs a WARNING, installs this anonymous Lifecycle, and any later call to verifyRestartable() throws RestartNotSupportedException with the original cause.

Common situations: Running Jenkins from a repackaged/custom war whose path does not match expectations, running inside a minimal container where /proc/self/exe or the classpath war location cannot be resolved, JVM security manager blocking reflection/native calls used by UnixLifecycle.

Related errors

AI-assisted analysis of jenkinsci/jenkins@2e228ff40b (2026-08-14). Data as JSON: /api/errors/9d42639c7aeb0faf. Report an issue: GitHub.