EIO

EIO

Error message

fuseConnectAsThreadUid: failed to open a libhdfs connection!  error %d.

What it means

Emitted by the fuse-dfs unlink handler when fuseConnectAsThreadUid() cannot obtain a libhdfs connection for the calling UID; rm on the mount fails with EIO. The protected-path check (EACCES) happens earlier and the actual hdfsDeleteWithTrash call happens later, so this message means the connection step itself failed before HDFS was contacted.

Source

Thrown at hadoop-hdfs-project/hadoop-hdfs-native-client/src/main/native/fuse-dfs/fuse_impls_unlink.c:45

  hdfsFS fs;
  int ret = 0;
  dfs_context *dfs = (dfs_context*)fuse_get_context()->private_data;

  TRACE1("unlink", path)

  assert(path);
  assert(dfs);
  assert('/' == *path);

  if (is_protected(path)) {
    ERROR("Trying to delete protected directory %s", path);
    ret = -EACCES;
    goto cleanup;
  }

  ret = fuseConnectAsThreadUid(&conn);
  if (ret) {
    fprintf(stderr, "fuseConnectAsThreadUid: failed to open a libhdfs "
            "connection!  error %d.\n", ret);
    ret = -EIO;
    goto cleanup;
  }
  fs = hdfsConnGetFs(conn);

  if (hdfsDeleteWithTrash(fs, path, dfs->usetrash)) {
    ERROR("Could not delete file %s", path);
    ret = (errno > 0) ? -errno : -EIO;
    goto cleanup;
  }
  ret = 0;

cleanup:
  if (conn) {
    hdfsConnRelease(conn);
  }
  return ret;

View on GitHub (pinned to 2add963021)

Solutions

Read the fuse-dfs stderr lines above this message for the fuseNewConnect/fuseConnect root cause.
kinit as the accessing user and confirm the ticket cache file for that uid exists.
Check NameNode reachability and fuse_dfs.conf: hdfs dfs -ls hdfs://<nn>:<port>/ must succeed from the same host and environment.
Ensure the uid resolves in local passwd (getent passwd <uid>).
Restart fuse_dfs with corrected environment and remount.

Defensive patterns

Strategy: validation

Validate before calling

# before deletion batches through the mount
klist -s || kinit "$USER"@EXAMPLE.COM
CLASSPATH="$(hdfs classpath --glob)" hdfs dfs -ls "${HDFS_URI:-hdfs://nn:8020/}" || exit 1

Try / catch

if (unlink(mount_file) < 0 && errno == EIO) {
    /* backend connect failed (EACCES would be protected path, ENOENT missing) */
    alert_backend_connection();
}

Prevention

Give deletion jobs fresh credentials or use keytab-based auto-renewal.
Map errnos precisely: EIO here never means 'file busy' - it is a backend connect failure.
Track fuse-dfs stderr for the fuseNewConnect line with the real cause.
Keep hadoop CLASSPATH and fuse_dfs.conf pinned in config management.

When it happens

Trigger: rm on the fuse-dfs mount when getUsername(uid) fails (no passwd entry), the uid's Kerberos ticket cache is missing (fuseNewConnect -> EACCES), or hdfsBuilderConnect fails (JVM/CLASSPATH, wrong namenode URI/port in fuse_dfs.conf, NameNode unreachable).

Common situations: Batch jobs deleting files hours after mount startup, past ticket expiry; fuse_dfs launched from cron/systemd without the Hadoop environment; hosts where /tmp ticket caches were purged.

Related errors

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