jenkinsci/jenkins · warning · RestartNotSupportedException

Restart is not supported on platforms without libc

Error message

Restart is not supported on platforms without libc

What it means

Thrown by UnixLifecycle.verifyRestartable() when Functions.isGlibcSupported() returns false. UnixLifecycle depends on the JNA-based LIBC binding (glibc) to perform the exec-based restart; without a usable libc/native binding, it cannot exec. This guards against attempting restart on a platform where the native calls would fail.

Source

Thrown at core/src/main/java/hudson/lifecycle/UnixLifecycle.java:91

        // close all files upon exec, except stdin, stdout, and stderr
        int sz = LIBC.getdtablesize();
        for (int i = 3; i < sz; i++) {
            int flags = LIBC.fcntl(i, F_GETFD);
            if (flags < 0) continue;
            LIBC.fcntl(i, F_SETFD, flags | FD_CLOEXEC);
        }

        // exec to self
        String exe = args.getFirst();
        LIBC.execvp(exe, new StringArray(args.toArray(new String[0])));
        throw new IOException("Failed to exec '" + exe + "' " + LIBC.strerror(Native.getLastError()));
    }

    @Override
    public void verifyRestartable() throws RestartNotSupportedException {
        if (!Functions.isGlibcSupported()) {
            throw new RestartNotSupportedException("Restart is not supported on platforms without libc");
        }

        // see http://lists.apple.com/archives/cocoa-dev/2005/Oct/msg00836.html and
        // http://factor-language.blogspot.com/2007/07/execve-returning-enotsup-on-mac-os-x.html
        // on Mac, execv fails with ENOTSUP if the caller is multi-threaded, resulting in an error like
        // the one described in http://www.nabble.com/Restarting-hudson-not-working-on-MacOS--to24641779.html
        //
        // according to http://www.mail-archive.com/wine-devel@winehq.org/msg66797.html this now works on Snow Leopard
        if (Platform.isDarwin() && !Platform.isSnowLeopardOrLater())
            throw new RestartNotSupportedException("Restart is not supported on Mac OS X");
    }

    private static final Logger LOGGER = Logger.getLogger(UnixLifecycle.class.getName());
}

View on GitHub (pinned to 2e228ff40b)

Solutions

  1. If on Alpine/musl, install the glibc compatibility package (e.g. libc6-compat or the Alpine gcompat package)
  2. Ensure the JNA library and its native stub are present and loadable on the classpath
  3. Run on a glibc-based Linux distribution (Debian/Ubuntu/RHEL) for full restart support
  4. If libc cannot be provided, restart Jenkins manually by stopping and starting the process
Defensive patterns

Strategy: validation

Validate before calling

if (!Functions.isGlibcSupported()) {
    // restart via UnixLifecycle will fail; plan to restart manually or use a process manager
}

Try / catch

try {
    Lifecycle.get().verifyRestartable();
} catch (RestartNotSupportedException e) {
    if (e.getMessage().contains("without libc")) {
        // JNA/glibc not available; restart manually
    }
}

Prevention

When it happens

Trigger: On a Unix host, Lifecycle.get() constructs UnixLifecycle; verifyRestartable() checks Functions.isGlibcSupported(). Returns false when JNA is absent, libc cannot be loaded, or the platform is not glibc-based (e.g. musl libc without compatibility, or a stripped JVM/JNA).

Common situations: Running Jenkins on Alpine Linux (musl libc) without glibc compatibility installed; JNA jar missing from the classpath/war; a JVM that blocks native library loading via security manager; running on an exotic Unix where glibc symbols are unavailable.

Related errors

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