vitest-dev/vitest · error · Error

--cache.dir is deprecated

Error message

--cache.dir is deprecated

What it means

Thrown by the `--cache` option transform when cache is configured as a non-boolean truthy value. In Vitest 4 the `--cache.dir` sub-option was removed; cache is now a simple boolean (default true) and the cache directory is managed internally. Passing an object/string (the old `cache: { dir: ... }` shape) triggers this deprecation-turned-error.

Source

Thrown at packages/vitest/src/node/cli/cli-config.ts:772

      'Threshold in milliseconds for a test or suite to be considered slow (default: `300`)',
    argument: '<threshold>',
  },
  teardownTimeout: {
    description:
      'Default timeout of a teardown function in milliseconds (default: `10000`)',
    argument: '<timeout>',
  },
  cache: {
    description: 'Enable cache',
    argument: '', // allow only boolean
    subcommands: {
      dir: null,
    },
    default: true,
    // cache can only be "false" or an object
    transform(cache) {
      if (typeof cache !== 'boolean' && cache) {
        throw new Error('--cache.dir is deprecated')
      }
      if (cache) {
        return {}
      }
      return cache
    },
  },
  maxConcurrency: {
    description: 'Maximum number of concurrent tests and suites during test file execution (default: `5`)',
    argument: '<number>',
  },
  fsModuleCache: {
    description: 'Cache transformed modules on the file system and reuse them between reruns (default: `false`)',
  },
  fsModuleCachePath: {
    description: 'Directory where the `fsModuleCache` is stored (default: `node_modules/.vitest-cache`)',
    argument: '<path>',
  },

View on GitHub (pinned to d568f8ce37)

Solutions

1. Remove `cache.dir` / `--cache.dir`. Use `--cache` (true, default) or `--no-cache` to toggle caching.
2. If you need to control where the cache lives, use the dedicated `fsModuleCachePath` option for module caching instead.
3. Update any shared config presets or Dockerfile/CI templates that reference `cache.dir`.

Example fix

// before
export default { cache: { dir: './.vitest-cache' } }
// after
export default { cache: true, fsModuleCachePath: './.vitest-cache' }

if (cache !== true && cache !== false) {
  throw new Error('cache must be a boolean in Vitest 4; cache.dir was removed')
}

function isCacheOption(v: unknown): v is boolean {
  return typeof v === 'boolean'
}

When it happens

Trigger: Using `--cache.dir=<path>` on the CLI, or setting `cache: { dir: '...' }` / `cache: 'somepath'` in config; the transform receives a non-boolean truthy value and throws because the old shape is no longer supported.

Common situations: Upgrading from Vitest 3 (or earlier) where `cache.dir` was valid; copying old config examples; CI configs that pinned a cache directory.

AI-assisted analysis of vitest-dev/vitest@d568f8ce37 (2026-08-03). Data as JSON: /data/errors/24b7896c70baabf3.json. Report an issue: GitHub.