denoland/deno · error · NodeSystemError

ERR_FS_CP_UNKNOWN

ERR_FS_CP_UNKNOWN

Error message

Cannot copy an unknown file type

What it means

ERR_FS_CP_UNKNOWN ('Cannot copy an unknown file type') is the fall-through in getStatsForCopy: when the stat bitmask from the native op matches none of the known source types (directory/file/char/block/symlink/socket/fifo), or when the native side reports kind 'UNKNOWN', the copy aborts rather than guessing. Typical source: a file whose type the stat call cannot classify in the current platform/permission context.

Source

Thrown at ext/node/polyfills/_fs/cp/cp.ts:116

      });
    case "SOCKET":
      throw new ERR_FS_CP_SOCKET({
        message: err.message,
        path: err.path,
        syscall: "cp",
        errno: EINVAL,
        code: "EINVAL",
      });
    case "FIFO":
      throw new ERR_FS_CP_FIFO_PIPE({
        message: err.message,
        path: err.path,
        syscall: "cp",
        errno: EINVAL,
        code: "EINVAL",
      });
    case "UNKNOWN":
      throw new ERR_FS_CP_UNKNOWN({
        message: err.message,
        path: err.path,
        syscall: "cp",
        errno: EINVAL,
        code: "EINVAL",
      });
    case "SYMLINK_TO_SUBDIRECTORY":
      throw new ERR_FS_CP_SYMLINK_TO_SUBDIRECTORY({
        message: err.message,
        path: err.path,
        syscall: "cp",
        errno: EINVAL,
        code: "EINVAL",
      });
    default:
      throw err;
  }
}

View on GitHub (pinned to 89f33cbef2)

Solutions

1. Narrow the copy to the files you know about (explicit list or filter on isFile/isDirectory)
2. Run the tool in an environment/user that can stat the tree normally, avoiding pseudo-filesystems
3. Wrap cp in try/catch on code ERR_FS_CP_UNKNOWN and report the path for manual handling

Example fix

// before
await fsp.cp(layerDir, outDir, { recursive: true }); // overlay whiteouts -> UNKNOWN

// after
try {
  await fsp.cp(layerDir, outDir, { recursive: true });
} catch (err) {
  if (err.code !== 'ERR_FS_CP_UNKNOWN') throw err;
  // fall back: copy only regular files
  await copyRegularFilesOnly(layerDir, outDir);
}

async function copyKnownTypesOnly(src, dest) {
  for await (const e of fsp.opendir(src)) {
    const st = await fsp.lstat(path.join(src, e.name));
    if (st.isFile()) await fsp.copyFile(path.join(src, e.name), path.join(dest, e.name));
    else if (st.isDirectory()) await copyKnownTypesOnly(path.join(src, e.name), path.join(dest, e.name));
  }
}

function isKnownCopyType(st) {
  return st.isFile() || st.isDirectory() || st.isSymbolicLink();
}

try {
  await fsp.cp(src, dest, { recursive: true });
} catch (err) {
  if (err.code !== 'ERR_FS_CP_UNKNOWN') throw err;
  await copyKnownTypesOnly(src, dest); // copy only regular files/dirs
}

When it happens

Trigger: Copying over filesystems that report exotic inode types (doors on illumos, whiteouts in overlayfs layers); stat succeeding but returning a type the flags enum does not cover.

Common situations: Reading inside container overlay layers or /proc-adjacent pseudo trees; cross-platform tooling hitting platform-specific file types.

Related errors

• ERR_FS_CP_EINVAL
• ERR_FS_CP_DIR_TO_NON_DIR
• ERR_FS_CP_NON_DIR_TO_DIR
• ERR_FS_CP_EEXIST
• ERR_FS_EISDIR

AI-assisted analysis of denoland/deno@89f33cbef2 (2026-08-16). Data as JSON: /api/errors/e551c259b5c0d4cd. Report an issue: GitHub.