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.

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)

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.