What causes "Don't know how to handle this file type" in yarnpkg/yarn?

Point `yarn publish` at a real directory containing package.json, or at an existing `.tgz` tarball file.

yarnpkg/yarn · error · Error

Don't know how to handle this file type

Error message

Don't know how to handle this file type

What it means

publish.js:55-61 stats the target path and branches on directory vs. regular file. If `lstat` returns anything that is neither a directory nor a regular file (a symlink whose target is gone, a socket, pipe, device, etc.), it throws the literal Error `Don't know how to handle this file type`.

Source

Thrown at src/cli/commands/publish.js:59

  if (access && access !== 'public' && access !== 'restricted') {
    throw new MessageError(config.reporter.lang('invalidAccess'));
  }

  // TODO this might modify package.json, do we need to reload it?
  await config.executeLifecycleScript('prepublish');
  await config.executeLifecycleScript('prepare');
  await config.executeLifecycleScript('prepublishOnly');
  await config.executeLifecycleScript('prepack');

  // get tarball stream
  const stat = await fs.lstat(dir);
  let stream;
  if (stat.isDirectory()) {
    stream = await pack(config);
  } else if (stat.isFile()) {
    stream = fs2.createReadStream(dir);
  } else {
    throw new Error("Don't know how to handle this file type");
  }
  const buffer = await new Promise((resolve, reject) => {
    const data = [];
    invariant(stream, 'expected stream');
    stream.on('data', data.push.bind(data)).on('end', () => resolve(Buffer.concat(data))).on('error', reject);
  });

  await config.executeLifecycleScript('postpack');

  // copy normalized package and remove internal keys as they may be sensitive or yarn specific
  pkg = Object.assign({}, pkg);
  for (const key in pkg) {
    if (key[0] === '_') {
      delete pkg[key];
    }
  }

  const tag = flags.tag || 'latest';

View on GitHub (pinned to c2dda503f3)

Solutions

Point `yarn publish` at a real directory containing package.json, or at an existing `.tgz` tarball file.
If you passed a symlink, resolve it to its real target or recreate the missing target.
Run `ls -la <path>` and `readlink -f <path>` to confirm the inode type before publishing.
Re-pack with `yarn pack` to produce a fresh `.tgz` and publish that.

Example fix

# before
$ yarn publish ./mylib.tgz.link   # dangling symlink
# after
$ yarn pack && yarn pack ./mylib.tgz   # or publish the real tarball
$ yarn publish ./mylib-v1.0.0.tgz

Defensive patterns

Strategy: validation

Validate before calling

const fs = require('fs').promises;
async function assertPublishable(path) {
  const st = await fs.lstat(path);
  if (!st.isDirectory() && !st.isFile()) {
    throw new Error(`Unsupported inode type for publish: ${path}`);
  }
}

Type guard

async function isDirOrFile(path) {
  const st = await require('fs').promises.lstat(path);
  return st.isDirectory() || st.isFile();
}

Try / catch

try {
  await runYarn(['publish', target]);
} catch (e) {
  if (/Don't know how to handle this file type/.test(e.message)) {
    console.error('Publish target must be a directory or a .tgz file.');
    return;
  }
  throw e;
}

Prevention

Always pass a directory or a packed `.tgz` to publish.
Resolve symlinks to their real targets before publishing.
Run `yarn pack` first and publish the resulting tarball.

When it happens

Trigger: Passing a broken symlink, a FIFO/socket, or a dangling special file as the publish target: `yarn publish ./some-symlink` whose target no longer exists, or a path that resolves to a non-file inode.

Common situations: Broken symlink left by a failed previous step; pointing at a path inside a virtual/overlay filesystem that surfaces as a special node; race where the file was removed between resolve and lstat.

Related errors

AI-assisted analysis of yarnpkg/yarn@c2dda503f3 (2026-08-13). Data as JSON: /api/errors/7725cb624ea79057. Report an issue: GitHub.