yarnpkg/yarn · error · MessageError

unknownFolderOrTarball

Error message

unknownFolderOrTarball

What it means

After resolving the publish path (`args[0]` or cwd, publish.js:131), yarn checks existence with `fs.exists(dir)`; a non-existent path throws unknownFolderOrTarball before it ever stats the target.

Source

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

      method: 'PUT',
      body: root,
    });
  } catch (error) {
    throw new MessageError(config.reporter.lang('publishFail', error.message));
  }

  await config.executeLifecycleScript('publish');
  await config.executeLifecycleScript('postpublish');
}

export async function run(config: Config, reporter: Reporter, flags: Object, args: Array<string>): Promise<void> {
  // validate arguments
  const dir = args[0] ? path.resolve(config.cwd, args[0]) : config.cwd;
  if (args.length > 1) {
    throw new MessageError(reporter.lang('tooManyArguments', 1));
  }
  if (!await fs.exists(dir)) {
    throw new MessageError(reporter.lang('unknownFolderOrTarball'));
  }

  const stat = await fs.lstat(dir);
  let publishPath = dir;
  if (stat.isDirectory()) {
    config.cwd = path.resolve(dir);
    publishPath = config.cwd;
  }

  // validate package fields that are required for publishing
  // $FlowFixMe
  const pkg = await config.readRootManifest();
  if (pkg.private) {
    throw new MessageError(reporter.lang('publishPrivate'));
  }
  if (!pkg.name) {
    throw new MessageError(reporter.lang('noName'));
  }

View on GitHub (pinned to c2dda503f3)

Solutions

1. Verify the path exists: `ls -la <path>` before publishing.
2. Ensure any `pack`/build step that produces the dir or tarball has completed first.
3. In scripts, default to cwd (`yarn publish`) or guard with `[ -e "$PKG_DIR" ]`.

Example fix

# before
$ yarn publish ./bulid        # typo, unknownFolderOrTarball
# after
$ yarn publish ./build

const fs = require('fs').promises;
async function assertTargetExists(p) {
  try { await fs.access(p); }
  catch { throw new Error(`Publish target does not exist: ${p}`); }
}

async function pathExists(p) {
  try { await require('fs').promises.access(p); return true; }
  catch { return false; }
}

try {
  await runYarn(['publish', target]);
} catch (e) {
  if (/unknownFolderOrTarball/.test(e.message)) {
    console.error(`Path not found: ${target}`);
    return;
  }
  throw e;
}

When it happens

Trigger: Running `yarn publish ./does-not-exist`, a typo'd relative path, or a path from an env var that wasn't set (resolving to an empty/garbage string).

Common situations: Typo in the directory name; CI passing an unset `${PKG_DIR}` variable; path computed before the artifact was created (e.g., pack hadn't run yet).

Related errors

• invalidAccess
• Don't know how to handle this file type
• tooManyArguments
• invalidPackageName
• publishFail

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