PrintExceptionAndFree: error determining class name of excep

Error message

PrintExceptionAndFree: error determining class name of exception.

What it means

While converting a Java exception thrown by an internal JNI call into an errno, libhdfs first asks the JVM for the exception's class name (classNameOfObject). If that JNI lookup itself fails, this message is printed, the class name is replaced with "(unknown)", and processing continues; because "(unknown)" matches no entry in the gExceptionInfo table, the caller receives EINTERNAL. It usually indicates the JVM itself is in trouble (most often OutOfMemoryError) rather than a problem with the original HDFS operation.

Source

Thrown at hadoop-hdfs-project/hadoop-hdfs-native-client/src/main/native/libhdfs/exception.c:160

        destroyLocalReference(env, jthr);
        return NULL;
    }
    destroyLocalReference(env, jStr);
    return excString;
}

int printExceptionAndFreeV(JNIEnv *env, jthrowable exc, int noPrintFlags,
        const char *fmt, va_list ap)
{
    int i, noPrint, excErrno;
    char *className = NULL;
    jthrowable jthr;
    const char *stackTrace;
    const char *rootCause;

    jthr = classNameOfObject(exc, env, &className);
    if (jthr) {
        fprintf(stderr, "PrintExceptionAndFree: error determining class name "
            "of exception.\n");
        className = strdup("(unknown)");
        destroyLocalReference(env, jthr);
    }
    for (i = 0; i < EXCEPTION_INFO_LEN; i++) {
        if (!strcmp(gExceptionInfo[i].name, className)) {
            break;
        }
    }
    if (i < EXCEPTION_INFO_LEN) {
        noPrint = (gExceptionInfo[i].noPrintFlag & noPrintFlags);
        excErrno = gExceptionInfo[i].excErrno;
    } else {
        noPrint = 0;
        excErrno = EINTERNAL;
    }

    // We don't want to use ExceptionDescribe here, because that requires a

View on GitHub (pinned to 2add963021)

Solutions

Check the adjacent stderr lines - the following '(unable to get root cause/stack trace)' lines and any JVM output usually identify the real failure.
Raise the libhdfs JVM heap: export LIBHDFS_OPTS="-Xmx2g" (or HADOOP_OPTS) and retry the operation.
Verify CLASSPATH holds one consistent set of hadoop-common/hadoop-hdfs jars matching the libhdfs build.
Test the same operation via `hdfs dfs` with the same CLASSPATH to separate JVM-side breakage from cluster-side problems.

Defensive patterns

Strategy: fallback

Try / catch

int ret = hdfsRename(fs, from, to);   /* any hdfs* call */
if (ret != 0) {
    /* diagnostics may themselves fail; probe both channels */
    const char *rc = hdfsGetLastExceptionRootCause();
    const char *st = hdfsGetLastExceptionStackTrace();
    log("hdfs failed errno=%d root=%s stack=%s", errno,
        rc ? rc : "(unavailable)", st ? st : "(unavailable)");
    /* ret/EINTERNAL with NULL diagnostics => suspect JVM health, not HDFS */
}

Prevention

Size the libhdfs JVM heap via LIBHDFS_OPTS="-Xmx..." for worst-case workload, not average.
Ship libhdfs with the hadoop-common/hdfs jars from the same release on CLASSPATH.
Treat EINTERNAL returns with '(unknown)' class names as a JVM-health signal and capture stderr at that moment.
Monitor JVM memory of processes embedding libhdfs alongside native RSS.

When it happens

Trigger: Any hdfs* call (hdfsOpenFile, hdfsRename, ...) whose JNI invocation throws, and while printExceptionAndFreeV processes the throwable, classNameOfObject also throws - e.g. the JVM cannot allocate the String for Class.getName(), or the JNIEnv is no longer healthy.

Common situations: JVM heap exhausted because LIBHDFS_OPTS/-Xmx is too small for the workload (large reads/writes, many threads); mismatched Hadoop jars causing class-resolution failures inside the JVM; long-running native processes with gradual JNI-reference or memory leaks.

Related errors

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