What causes "Unknown entry: ${entry}" in parcel-bundler/parcel?

Check if the entry is a broken symlink: ls -la and readlink .

parcel-bundler/parcel · error · ThrowableDiagnostic

Unknown entry: ${entry}

Error message

Unknown entry: ${entry}

What it means

Thrown by resolveEntry() as the final fallthrough after the isDirectory() and isFile() branches both fail to match. The entry's stat result is neither a directory nor a regular file, so Parcel does not know how to handle it.

Source

Thrown at packages/core/core/src/requests/EntryRequest.js:344

        this.options.inputFS.cwd(),
        projectRoot,
      )
        ? this.options.inputFS.cwd()
        : projectRoot;

      return {
        entries: [
          {
            filePath: toProjectPath(this.options.projectRoot, entry),
            packagePath: toProjectPath(this.options.projectRoot, packagePath),
          },
        ],
        files: [],
        globs: [],
      };
    }

    throw new ThrowableDiagnostic({
      diagnostic: {
        message: md`Unknown entry: ${entry}`,
      },
    });
  }

  async readPackage(entry: FilePath): Promise<?{
    ...PackageJSON,
    filePath: FilePath,
    map: {|data: mixed, pointers: {|[string]: Mapping|}|},
    ...
  }> {
    let content, pkg;
    let pkgFile = path.join(entry, 'package.json');
    try {
      content = await this.options.inputFS.readFile(pkgFile, 'utf8');
    } catch (err) {
      return null;

View on GitHub (pinned to 59484858a1)

Solutions

Check if the entry is a broken symlink: ls -la <entry> and readlink <entry>.
Remove the broken symlink and recreate it pointing at a real file.
Ensure the entry path is a regular file or directory, not a socket/pipe/device.
Run stat <entry> to inspect the file type reported by the OS.

Example fix

// before — broken symlink
ln -s /nonexistent src/index.html
parcel src/index.html

// after
rm src/index.html && echo '<html></html>' > src/index.html
parcel src/index.html

Defensive patterns

Strategy: validation

Validate before calling

const fs = require('fs');
function validateEntryIsFileOrDir(entry) {
  const stat = fs.lstatSync(entry);
  if (stat.isSymbolicLink()) {
    const real = fs.realpathSync(entry); // throws if broken
  }
  if (!stat.isFile() && !stat.isDirectory()) {
    throw new Error(`Entry ${entry} is neither a file nor directory (type: unknown).`);
  }
}

Prevention

Check for broken symlinks with ls -la before building.
Avoid pointing Parcel at special files (sockets, pipes).
In CI, verify entry paths resolve to regular files.

When it happens

Trigger: Reached when stat(entry) succeeds but both stat.isDirectory() and stat.isFile() are false. This covers special filesystem entries: broken symlinks, FIFOs/named pipes, sockets, character/block devices, or filesystems where stat reports an unusual type.

Common situations: Entry path is a broken symlink (target deleted); entry is a Unix socket or named pipe left by another process; pointing at /dev/null or a device file; NFS/network filesystem quirks reporting odd file types.

Related errors

AI-assisted analysis of parcel-bundler/parcel@59484858a1 (2026-08-13). Data as JSON: /api/errors/8b3a282c35e22339. Report an issue: GitHub.