What causes "getJNIEnv: getGlobalJNIEnv failed " in apache/hadoop?

Read the stderr line(s) directly above this message — they name the root cause (CLASSPATH, JVM code, a ClassNotFoundException/NoClassDefFoundError, or a pthread error)

apache/hadoop · error

getJNIEnv: getGlobalJNIEnv failed

Error message

getJNIEnv: getGlobalJNIEnv failed

What it means

This is the umbrella failure at the fail label of getJNIEnv(): one of the inner bootstrap steps broke — getGlobalJNIEnv() returned NULL (see the CLASSPATH / JNI_CreateJavaVM / AttachCurrentThread messages), initCachedClasses() threw (a class-resolution failure printed just above), or threadLocalStorageSet() failed. hdfsThreadDestructor frees the partial state, getJNIEnv returns NULL, and the current API call fails with EINTERNAL. The true cause is always the stderr line printed immediately before this one.

Source

Thrown at hadoop-hdfs-project/hadoop-hdfs-native-client/src/main/native/libhdfs/jni_helper.c:849

      mutexUnlock(&jvmMutex);
      printExceptionAndFree(state->env, jthr, PRINT_EXC_ALL,
                            "initCachedClasses failed");
      goto fail;
    }

    if (threadLocalStorageSet(state)) {
      mutexUnlock(&jvmMutex);
      goto fail;
    }

    // set the TLS var only when the state passes all the checks
    THREAD_LOCAL_STORAGE_SET_QUICK(state);
    mutexUnlock(&jvmMutex);

    return state->env;

fail:
    fprintf(stderr, "getJNIEnv: getGlobalJNIEnv failed\n");
    hdfsThreadDestructor(state);
    return NULL;
}

char* getLastTLSExceptionRootCause()
{
    struct ThreadLocalState *state = NULL;
    THREAD_LOCAL_STORAGE_GET_QUICK(&state);
    if (!state) {
        mutexLock(&jvmMutex);
        if (threadLocalStorageGet(&state)) {
            mutexUnlock(&jvmMutex);
            return NULL;
        }
        mutexUnlock(&jvmMutex);
    }
    return state->lastExceptionRootCause;
}

View on GitHub (pinned to 2add963021)

Solutions

Read the stderr line(s) directly above this message — they name the root cause (CLASSPATH, JVM code, a ClassNotFoundException/NoClassDefFoundError, or a pthread error)
If a class-loading exception appears, re-export CLASSPATH=$(hadoop classpath --glob) for the exact Hadoop version the app was linked against
If a JVM create/attach code appears, apply the fixes for those errors (LIBHDFS_OPTS, JVM alignment)
Do not chase this message itself; it only reports that init failed

Defensive patterns

Strategy: try-catch

Validate before calling

/* Startup self-test: proves CLASSPATH, JVM options, and cached classes all init */
hdfsFS fs = hdfsConnect("default", 0);
if (!fs) return EXIT_FAILURE;
hdfsDisconnect(fs);

Try / catch

hdfsFS fs = hdfsConnect("default", 0);
if (!fs) {
    /* the stderr line just above this failure names the true cause */
    fprintf(stderr, "libhdfs init failed (errno=%d)\n", errno);
    return EXIT_FAILURE;
}

Prevention

Capture the process stderr during first libhdfs use — the root-cause line precedes the umbrella message
Add a boot-time self-test (connect + hdfsExists on a known path) so init failures surface at startup
Regenerate CLASSPATH whenever the Hadoop installation is upgraded

When it happens

Trigger: Any first-time per-thread init failure: missing CLASSPATH, JVM creation error, attach error, a Java exception while caching classes such as org.apache.hadoop.fs.FileSystem (classpath set but Hadoop jars missing or wrong version), or a pthread_setspecific failure.

Common situations: Same roots as the JVM bootstrap errors: CLASSPATH pointing at the wrong Hadoop version so classes fail to load even though the variable is set; bad LIBHDFS_OPTS; resource exhaustion. Typically seen on the first call after a deploy.

Related errors

AI-assisted analysis of apache/hadoop@2add963021 (2026-08-22). Data as JSON: /api/errors/a21f7e4d3a47fb33. Report an issue: GitHub.