yarnpkg/yarn · error · MessageError

couldntFindPackageInCache

Error message

couldntFindPackageInCache

What it means

During offline resolution, if no cached version satisfies the range (resolveConstraints returns null) and preferOffline is false, Yarn throws because it cannot reach the network and has no matching cache entry.

Source

Thrown at src/resolvers/registries/npm-resolver.js:140

        continue;
      }

      // read package metadata
      const metadata = await this.config.readPackageMetadata(dir);
      if (!metadata.remote) {
        continue; // old yarn metadata
      }

      versions[pkg.version] = Object.assign({}, pkg, {
        _remote: metadata.remote,
      });
    }

    const satisfied = await this.config.resolveConstraints(Object.keys(versions), this.range);
    if (satisfied) {
      return versions[satisfied];
    } else if (!this.config.preferOffline) {
      throw new MessageError(
        this.reporter.lang('couldntFindPackageInCache', this.name, this.range, Object.keys(versions).join(', ')),
      );
    } else {
      return null;
    }
  }

  cleanRegistry(url: string): string {
    if (this.config.getOption('registry') === YARN_REGISTRY) {
      return url.replace(NPM_REGISTRY_RE, YARN_REGISTRY);
    } else {
      return url;
    }
  }

  async resolve(): Promise<Manifest> {
    // lockfile
    const shrunk = this.request.getLocked('tarball');

View on GitHub (pinned to c2dda503f3)

Solutions

1. Run yarn install online first to populate the cache
2. Remove the --offline flag to allow network resolution
3. Run yarn cache clean followed by a fresh online install
4. Use --prefer-offline instead of --offline to allow fallback to network

// Verify cache has a satisfying version before going offline
const cachedVersions = await getCachedVersions(config, name);
if (!semver.maxSatisfying(cachedVersions, range)) {
  console.warn(`No cached version of ${name} satisfies ${range}; online install needed`);
}

function cacheSatisfies(cachedVersions: string[], range: string): boolean {
  return semver.maxSatisfying(cachedVersions, range) !== null;
}

try {
  const manifest = await resolver.resolveRequestOffline();
} catch (e) {
  if (e.message.includes('couldntFindPackageInCache')) {
    // retry without --offline to fetch from the network
  }
}

When it happens

Trigger: Running with --offline (config.offline true) where the cache lacks any version satisfying the requested range. The else-if (!preferOffline) branch throws.

Common situations: CI without network access; air-gapped environments; stale cache after a version bump that was never fetched online.

Related errors

• importResolveFailed
• Yarn hasn't been able to find a cache folder it can use. Ple
• ENOENT
• Incorrect integrity when fetching from the cache for $0. Cac
• Incorrect hash when fetching from the cache for $0. Cache ha

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