threadLocalStorageSet: pthread_setspecific failed with error

Error message

threadLocalStorageSet: pthread_setspecific failed with error %d

What it means

pthread_setspecific failed while binding the freshly built ThreadLocalState to the thread: EINVAL means gTlsKey is invalid (never created or destroyed), ENOMEM means insufficient memory. The wrapper then calls hdfsThreadDestructor(state), which frees the state, so it must not be used afterwards; getJNIEnv fails and the umbrella 'getGlobalJNIEnv failed' message follows.

Source

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

  if (!gTlsKeyInitialized) {
    ret = pthread_key_create(&gTlsKey, hdfsThreadDestructor);
    if (ret) {
      fprintf(stderr,
        "threadLocalStorageGet: pthread_key_create failed with error %d\n",
        ret);
      return ret;
    }
    gTlsKeyInitialized = 1;
  }
  *state = pthread_getspecific(gTlsKey);
  return ret;
}

int threadLocalStorageSet(struct ThreadLocalState *state)
{
  int ret = pthread_setspecific(gTlsKey, state);
  if (ret) {
    fprintf(stderr,
      "threadLocalStorageSet: pthread_setspecific failed with error %d\n",
      ret);
    hdfsThreadDestructor(state);
  }
  return ret;
}

View on GitHub (pinned to 2add963021)

Solutions

Address ENOMEM as an OOM condition (raise limits, fix leaks)
If EINVAL, suspect corruption of libhdfs globals or repeated dlclose/dlopen of the library; rebuild/upgrade libhdfs
Capture the numeric code from the message to distinguish ENOMEM from EINVAL

Defensive patterns

Strategy: retry

Try / catch

if (anyHdfsCall() == -1 && errno == EINTERNAL) {
    /* if stderr shows setspecific ENOMEM, address memory first */
    free_cache();
    retry_once();
}

Prevention

Keep native heap headroom in memory-capped deployments
Do not dlopen/dlclose libhdfs repeatedly — its TLS state is process-wide
Distinguish ENOMEM from EINVAL in the message before choosing a fix

When it happens

Trigger: Torn initialization (key flagged initialized but actually invalid) or ENOMEM under memory pressure at first per-thread setup. Rare in practice.

Common situations: Same conditions as OOM; memory corruption of libhdfs globals; unsupported dlopen/dlclose reuse patterns.

Related errors

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