vercel/next.js · error · io::Error

InvalidFilename

InvalidFilename

Error message

file {name_or_path} is too long ({len}) exceeds filesystem limit of {limit}

What it means

validate_path_length enforces conservative OS filesystem limits before any disk write. On Unix it rejects filenames whose byte length exceeds 255 (the common ext4/btrfs/xfs inode name limit); on macOS it also rejects total paths over 1016 bytes; on Windows it rejects verbatim paths over 32667 characters. The error is returned as io::ErrorKind::InvalidFilename.

Source

Thrown at turbopack/crates/turbo-tasks-fs/src/disk.rs:74

///   32767 characters long.
/// - On macOS, the limit is traditionally 255 characters for the file name and a second limit of
///   1024 for the entire path (verified by running `getconf PATH_MAX /`).
/// - On Linux, the limit differs between kernel (and by extension, distro) and filesystem. On most
///   common file systems (e.g. ext4, btrfs, and xfs), individual file names can be up to 255 bytes
///   with no hard limit on total path length. [Some legacy POSIX APIs are restricted to the
///   `PATH_MAX` value of 4096 bytes in `limits.h`, but most applications support longer
///   paths][PATH_MAX].
///
/// For more details, refer to <https://en.wikipedia.org/wiki/Comparison_of_file_systems#Limits>.
///
/// Realistically, the output path lengths will be the same across all platforms, so we need to set
/// a conservative limit and be particular about when we decide to bump it. Here we have opted for
/// 255 characters, because it is the shortest of the three options.
///
/// [PATH_MAX]: https://eklitzke.org/path-max-is-tricky
pub fn validate_path_length(path: &Path) -> io::Result<()> {
    fn error(name_or_path: &str, len: usize, limit: usize) -> io::Error {
        io::Error::new(
            io::ErrorKind::InvalidFilename,
            format!("file {name_or_path} is too long ({len}) exceeds filesystem limit of {limit}"),
        )
    }
    if cfg!(windows) {
        // We always use verbatim paths internally in turbo-tasks-fs
        debug_assert!(
            matches!(
                path.components().next(),
                Some(std::path::Component::Prefix(prefix)) if prefix.kind().is_verbatim()
            ),
            "expected a verbatim path, got {path:?}",
        );

        // We subtract a 100-character safety margin from the real value because:
        // > The maximum path of 32,767 characters is approximate, because the "\\?\" prefix may
        // > be expanded to a longer string by the system at run time, and this expansion
        // > applies to the total length.

View on GitHub (pinned to 0ae8c72462)

Solutions

Shorten the source module/route names that feed into the generated filename.
Configure chunk/asset naming to use a hash-only or shorter template to stay under 255 bytes.
Move the output directory closer to the filesystem root to reduce total path length (macOS).

Example fix

// before: long deterministic chunk name
config.output = { filename: '[name].[contenthash].js' } // name can be hundreds of chars

// after: hash-prefixed short name
config.output = { filename: '[contenthash:8].js' }

Defensive patterns

Strategy: validation

Validate before calling

// Check generated output filenames stay under the 255-byte limit (Node.js).
const MAX_NAME = 255;
function assertNameLength(name) {
  const len = Buffer.byteLength(name, 'utf8');
  if (len > MAX_NAME) throw new Error(`filename too long: ${len} > ${MAX_NAME} bytes`);
}

Prevention

Use hash-based or short chunk-naming templates to keep generated filenames compact.
Avoid extremely long route/component names that flow into output filenames.
On macOS, keep the output directory shallow to stay under the ~1KB total path limit.

When it happens

Trigger: Turbopack generating an output asset/chunk whose filename exceeds 255 bytes — e.g. a content-hashed name with a very long original module identifier, or a deeply-named server-component chunk. Also macOS builds with total output paths exceeding ~1KB.

Common situations: Very long route segment or component names producing oversized chunk filenames; aggregated chunk names built from many concatenated module names; builds targeting macOS with deep output directory trees.

Related errors

AI-assisted analysis of vercel/next.js@0ae8c72462 (2026-08-06). Data as JSON: /api/errors/e59257919fd37eb7. Report an issue: GitHub.