yarnpkg/yarn · error · MessageError

Yarn hasn't been able to find a cache folder it can use. Ple

Error message

Yarn hasn't been able to find a cache folder it can use. Please use the explicit --cache-folder option to tell it what location to use, or make one of the preferred locations writable.

What it means

Thrown when Yarn cannot locate any writable cache folder. Yarn first honors `--cache-folder` / `cache-folder` option, then probes `constants.PREFERRED_MODULE_CACHE_DIRECTORIES` (e.g. ~/.cache/yarn, XDG dirs) for write+execute+read access via `getFirstSuitableFolder`. If none is writable, `cacheRootFolder` stays falsy and this error fires.

Source

Thrown at src/config.js:377

        preferredCacheFolders = [String(preferredCacheFolder)].concat(preferredCacheFolders);
      }

      const cacheFolderQuery = await fs.getFirstSuitableFolder(
        preferredCacheFolders,
        fs.constants.W_OK | fs.constants.X_OK | fs.constants.R_OK, // eslint-disable-line no-bitwise
      );
      for (const skippedEntry of cacheFolderQuery.skipped) {
        this.reporter.warn(this.reporter.lang('cacheFolderSkipped', skippedEntry.folder));
      }

      cacheRootFolder = cacheFolderQuery.folder;
      if (cacheRootFolder && cacheFolderQuery.skipped.length > 0) {
        this.reporter.warn(this.reporter.lang('cacheFolderSelected', cacheRootFolder));
      }
    }

    if (!cacheRootFolder) {
      throw new MessageError(this.reporter.lang('cacheFolderMissing'));
    } else {
      this._cacheRootFolder = String(cacheRootFolder);
    }

    const manifest = await this.maybeReadManifest(this.lockfileFolder);

    const plugnplayByEnv = this.getOption('plugnplay-override');
    if (plugnplayByEnv != null) {
      this.plugnplayEnabled = plugnplayByEnv !== 'false' && plugnplayByEnv !== '0';
      this.plugnplayPersist = false;
    } else if (opts.enablePnp || opts.disablePnp) {
      this.plugnplayEnabled = !!opts.enablePnp;
      this.plugnplayPersist = true;
    } else if (manifest && manifest.installConfig && manifest.installConfig.pnp) {
      this.plugnplayEnabled = !!manifest.installConfig.pnp;
      this.plugnplayPersist = false;
    } else {
      this.plugnplayEnabled = false;

View on GitHub (pinned to c2dda503f3)

Solutions

1. Pass `--cache-folder <writable-path>` on the command line.
2. Set `cache-folder "<path>"` in .yarnrc.
3. Ensure $HOME or XDG_CACHE_HOME is writable by the current user (`chmod`/`chown`).
4. In containers, create and chmod a cache dir, then point Yarn at it: `mkdir -p /tmp/yarn-cache && yarn --cache-folder /tmp/yarn-cache`.

Example fix

# before
yarn install
# after
yarn install --cache-folder /tmp/yarn-cache
# or in .yarnrc:
# cache-folder "/tmp/yarn-cache"

const fs = require('fs');
const path = require('path');

function findWritableCacheFolder(candidates) {
  for (const dir of candidates) {
    try {
      fs.mkdirSync(dir, {recursive: true});
      fs.accessSync(dir, fs.constants.W_OK | fs.constants.X_OK | fs.constants.R_OK);
      return dir;
    } catch {}
  }
  return null;
}

const cache = findWritableCacheFolder([
  process.env.XDG_CACHE_HOME && path.join(process.env.XDG_CACHE_HOME, 'yarn'),
  path.join(process.env.HOME || '/tmp', '.cache', 'yarn'),
  '/tmp/yarn-cache',
]);
if (!cache) {
  console.error('No writable cache folder — pass --cache-folder <path>.');
  process.exit(1);
}
process.env.YARN_CACHE_FOLDER = cache;

try {
  await config.init(opts);
} catch (err) {
  if (err.message.includes('cache folder')) {
    // retry with an explicit writable temp cache folder
    opts.cacheFolder = '/tmp/yarn-cache';
    await fs.mkdirp(opts.cacheFolder);
    await config.init(opts);
  } else {
    throw err;
  }
}

When it happens

Trigger: All preferred cache directories are read-only or non-creatable (locked-down environment, container with read-only home, restricted CI runner), and no explicit `--cache-folder` was passed.

Common situations: CI containers where $HOME is read-only. Docker images running as a non-root user without a writable home. Systems where XDG_CACHE_HOME points to an unwritable path. Disk-full conditions.

Related errors

• noPermission
• Don't know how to handle this file type
• unknownFolderOrTarball
• unknownPackageName
• linkMissing

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