{"record":{"id":"e25d3612f6c6656b","repo":"vercel/next.js","slug":"invalid-handler-fields-configured-for-cachehandle","errorCode":null,"errorMessage":"Invalid handler fields configured for \"cacheHandlers\":\n${invalidHandlerItems.map((item) => `${key}: ${item.reason}`).join('\\n')}","messagePattern":"Invalid handler fields configured for \"cacheHandlers\":\n(.+?): (.+?)`\\)\\.join\\('\\\\n'\\)\\}","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/next/src/server/config.ts","lineNumber":1482,"sourceCode":"      } else {\n        const handlerPath = (\n          result.cacheHandlers as {\n            [handlerName: string]: string | undefined\n          }\n        )[key]\n\n        const resolvedHandlerPath =\n          handlerPath && resolveCacheHandlerPathToFilesystem(handlerPath)\n\n        if (resolvedHandlerPath && !existsSync(resolvedHandlerPath)) {\n          invalidHandlerItems.push({\n            key,\n            reason: `cache handler path provided does not exist, received ${handlerPath}`,\n          })\n        }\n      }\n      if (invalidHandlerItems.length) {\n        throw new Error(\n          `Invalid handler fields configured for \"cacheHandlers\":\\n${invalidHandlerItems.map((item) => `${key}: ${item.reason}`).join('\\n')}`\n        )\n      }\n    }\n  }\n\n  const userProvidedModularizeImports = result.modularizeImports\n  // Unfortunately these packages end up re-exporting 10600 modules, for example: https://unpkg.com/browse/@mui/icons-material@5.11.16/esm/index.js.\n  // Leveraging modularizeImports tremendously reduces compile times for these.\n  result.modularizeImports = {\n    ...(userProvidedModularizeImports || {}),\n    // This is intentionally added after the user-provided modularizeImports config.\n    '@mui/icons-material': {\n      transform: '@mui/icons-material/{{member}}',\n    },\n    lodash: {\n      transform: 'lodash/{{member}}',\n    },","sourceCodeStart":1464,"sourceCodeEnd":1500,"githubUrl":"https://github.com/vercel/next.js/blob/0ae8c72462952df163f1b1e0726641bc5b40dc93/packages/next/src/server/config.ts#L1464-L1500","documentation":"Thrown at config.ts:1482 when one or more `cacheHandlers` keys are invalid. A key is invalid if it is `'private'` (the `use cache: private` handler cannot be customized), if it fails the `/^[a-z-]+$/` regex (uppercase, digits, underscores), or if the resolved handler file path does not exist on disk (`existsSync`). The error aggregates all invalid items with their reasons.","triggerScenarios":"`cacheHandlers: { Private: '/x.js' }` or `{ private: '/x.js' }` (reserved name); `{ 'use_cache': '/x.js' }` (underscore not allowed); `{ default: './nonexistent.js' }` (file missing); `{ default: 'myHandler' }` where the resolved path does not exist.","commonSituations":"Pointing to a handler path that hasn't been created yet; using camelCase or snake_case keys; trying to override the built-in `private` handler.","solutions":["Rename handler keys to lowercase kebab-case using only a-z and hyphens.","Remove any `private` entry — it is reserved and cannot be overridden.","Ensure each handler path resolves to an existing file; use an absolute path or correct relative path.","Create the missing handler module before referencing it."],"exampleFix":"// before\nmodule.exports = { cacheHandlers: { private: './priv.js', 'use_cache': './missing.js' } }\n// after\nmodule.exports = { cacheHandlers: { default: './handlers/my-cache.js' } } // create ./handlers/my-cache.js first","handlingStrategy":"validation","validationCode":"import { existsSync } from 'fs';\nconst allowedKey = /^[a-z-]+$/;\nfor (const [key, path] of Object.entries(cacheHandlers)) {\n  if (key === 'private') throw new Error('private is reserved');\n  if (!allowedKey.test(key)) throw new Error(`bad key ${key}`);\n  if (path && !existsSync(path)) throw new Error(`missing handler ${path}`);\n}","typeGuard":"function isValidHandlerEntry(key: string, path: string): boolean {\n  return key !== 'private' && /^[a-z-]+$/.test(key) && (path === undefined || existsSync(path));\n}","tryCatchPattern":null,"preventionTips":["Use only lowercase a-z and hyphens in handler keys.","Never override the reserved `private` handler.","Create handler files before referencing them, and prefer absolute paths."],"tags":["config","cache","validation","filesystem"],"analyzedSha":"0ae8c72462952df163f1b1e0726641bc5b40dc93","analyzedAt":"2026-08-06T19:44:29.143Z","schemaVersion":2},"datasetVersion":"2026-08-07T02:17:10.218Z"}