vitest-dev/vitest · error · Error

--cache.dir is deprecated

Error message

--cache.dir is deprecated

What it means

`--cache.dir` was removed in Vitest 4. The `cache` option is now only a boolean (`true`/`false`) or an empty object; passing a non-boolean truthy value (such as `{ dir: '...' }`) trips the `transform` and reports the deprecation as a hard error.

Solutions

1. Remove `cache.dir` from CLI and config; let Vitest use its default cache location.
2. Set `test.cache` to a boolean: `cache: true` (or omit) / `cache: false`.
3. If you need to relocate the cache, set the appropriate environment/Temp dir or open a feature request rather than reusing the removed key.

Example fix

// before (v3)
export default defineConfig({ test: { cache: { dir: './.vitest' } } })

// after (v4)
export default defineConfig({ test: { cache: true } })

import type { InlineConfig } from 'vitest/config'

function migrateCache(cfg: any): InlineConfig['test'] {
  if (cfg?.test?.cache && typeof cfg.test.cache === 'object' && 'dir' in cfg.test.cache) {
    console.warn('test.cache.dir was removed in Vitest 4; ignoring.')
    return { ...cfg.test, cache: true }
  }
  return cfg.test
}

function isV4CacheShape(cache: unknown): cache is boolean {
  return cache === undefined || typeof cache === 'boolean' || cache === null
}

When it happens

Trigger: Calling `vitest --cache.dir=.cache`, providing `test: { cache: { dir: './.vitest' } }` in config, or merging an old config that still sets `cache.dir`. The check is `typeof cache !== 'boolean' && cache`.

Common situations: Upgrading from Vitest 3 (or earlier) where `cache.dir` was valid; a shared config preset that has not been updated; tooling (Nx, Turborepo generators) emitting the v3 shape.

Related errors

• The `test.workspace` option was removed in Vitest 4…
• "browser.instances" was set in the config, but the array is…
• Environment " " is not a valid environment. Path " " should…
• Inspector host cannot be a URL. Use "host:port" instead of
• Looks like you set "test.environment" to "browser". To…

AI-assisted analysis of vitest-dev/vitest@1fa9837ec2 (2026-08-11). Data as JSON: /api/errors/24b7896c70baabf3. Report an issue: GitHub.

Appendix: 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 1fa9837ec2)