EIO

EIO

Error message

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

What it means

Emitted by the fuse-dfs truncate handler when fuseConnectAsThreadUid() cannot obtain a libhdfs connection during a truncate-to-zero (which is implemented as dfs_unlink followed by recreating an empty file via hdfsOpenFile with O_WRONLY|O_CREAT). Truncates to a non-zero size silently return success without effect (an HDFS limitation); this error fires on the recreate step's connection failure and returns EIO. Note the file may already have been unlinked by the time this error is returned.

Solutions

Check fuse-dfs stderr above this message - fuseNewConnect names the cause (kinit hint or connect error code).
Refresh Kerberos credentials for the calling uid (kinit) and retry.
Verify the file state after this error - dfs_unlink already ran, so the file may be gone even though truncate reported EIO.
Validate fuse_dfs.conf namenode URI/port and NameNode health with hdfs dfs -ls.
Restart fuse_dfs with a correct CLASSPATH/LIBHDFS_OPTS if the JVM failed to start.

Defensive patterns

Strategy: validation

Validate before calling

# before truncate-style log rotation through the mount
klist -s || kinit "$USER"@EXAMPLE.COM
CLASSPATH="$(hdfs classpath --glob)" hdfs dfs -ls "${HDFS_URI:-hdfs://nn:8020/}" || exit 1
# note: only truncate -s 0 has any effect through fuse-dfs

Try / catch

if (truncate(mount_file, 0) < 0 && errno == EIO) {
    /* recreate step could not connect; the file may already be unlinked - verify */
    check_file_exists_and_recreate();
}

Prevention

Remember fuse-dfs truncate-to-zero = unlink + recreate: on EIO the file may already be gone.
Do not rely on truncate to non-zero sizes through the mount - it silently succeeds with no effect.
Run log rotation with valid Kerberos credentials; rotation windows are the classic ticket-expiry trap.
Keep an unlogged-copy or HDFS snapshot policy if truncation-based rotation is used.

When it happens

Trigger: truncate -s 0, shell redirection > file, or editors that truncate, when getUsername(uid) fails, the uid's Kerberos ticket cache is missing/stale, or hdfsBuilderConnect fails (CLASSPATH/JVM, wrong namenode URI/port, NameNode unreachable).

Common situations: Log-rotation scripts using truncate/-s 0 or copytruncate-style reopening on a Kerberized mount whose ticket expired; fuse_dfs environment losing Hadoop jars after a restart; uid without a passwd entry.

Related errors

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

Appendix: source

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

  TRACE1("truncate", path)

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

  if (size != 0) {
    return 0;
  }

  int ret = dfs_unlink(path);
  if (ret != 0) {
    return ret;
  }

  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);

  int flags = O_WRONLY | O_CREAT;

  hdfsFile file;
  if ((file = (hdfsFile)hdfsOpenFile(fs, path, flags,  0, 0, 0)) == NULL) {
    ERROR("Could not connect open file %s", path);
    ret = -EIO;
    goto cleanup;
  }

  if (hdfsCloseFile(fs, file) != 0) {
    ERROR("Could not close file %s", path);
    ret = -EIO;

View on GitHub (pinned to 2add963021)