What causes "tlsCallback: TlsFree failed with error %d " in apache/hadoop?

Ignore when it occurs during natural process exit

tlsCallback: TlsFree failed with error %d

Error message

tlsCallback: TlsFree failed with error %d

What it means

At DLL_PROCESS_DETACH the TLS callback frees the process-wide TLS index with TlsFree; the call failed and GetLastError is printed. This happens only during unload/exit; consequences are negligible because the OS reclaims TLS slots at process death, but it can indicate the index was already freed (double unload) or teardown under memory pressure.

Source

Thrown at hadoop-hdfs-project/hadoop-hdfs-native-client/src/main/native/libhdfs/os/windows/thread_local_storage.c:159

 * Windows application attempts to use it via explicit linking.
 *
 * @param h module handle
 * @param reason the reason for calling the callback
 * @param pv reserved, unused
 */
static void NTAPI tlsCallback(PVOID h, DWORD reason, PVOID pv)
{
  DWORD tlsIndex;
  switch (reason) {
  case DLL_THREAD_DETACH:
    detachCurrentThreadFromJvm();
    break;
  case DLL_PROCESS_DETACH:
    detachCurrentThreadFromJvm();
    tlsIndex = gTlsIndex;
    gTlsIndex = TLS_OUT_OF_INDEXES;
    if (!TlsFree(tlsIndex)) {
      fprintf(stderr, "tlsCallback: TlsFree failed with error %d\n",
        GetLastError());
    }
    break;
  default:
    break;
  }
}

/*
 * A variable named _tls_used contains the TLS directory, which contains a list
 * of pointers to callback functions.  Normally, the linker won't retain this
 * variable unless the executable has implicit thread-local variables, defined
 * using the __declspec(thread) extended storage-class modifier.  libhdfs
 * doesn't use __declspec(thread), and we have no guarantee that the executable
 * linked to libhdfs will use __declspec(thread).  By forcing the linker to
 * reference _tls_used, we guarantee that the binary retains the TLS directory.
 * See Microsoft Visual Studio 10.0/VC/crt/src/tlssup.c .
 */

View on GitHub (pinned to 2add963021)

Solutions

Ignore when it occurs during natural process exit
Do not dlopen/dlclose libhdfs repeatedly — its TLS index and JVM state are process-wide and not designed for reload cycles
Check loader logs for double-unload of the DLL

Defensive patterns

Strategy: fallback

Prevention

Do not dlopen/dlclose libhdfs in cycles; keep it loaded for the process lifetime
Avoid explicit FreeLibrary before exit
Ignore this line when it occurs during normal process termination

When it happens

Trigger: DLL unload where gTlsIndex was already freed or set to TLS_OUT_OF_INDEXES by a prior detach; FreeLibrary followed by exit-time callbacks; loader races during process termination.

Common situations: Explicit FreeLibrary of libhdfs before process exit; DLL unload ordering issues in plugin hosts.

Related errors

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