{"record":{"id":"899b631ccdbcacff","repo":"vercel/next.js","slug":"invalid-cachehandlers-provided-expected-an-obje","errorCode":null,"errorMessage":"Invalid \"cacheHandlers\" provided, expected an object e.g. { default: '/my-handler.js' }, received ${JSON.stringify(result.cacheHandlers)}","messagePattern":"Invalid \"cacheHandlers\" provided, expected an object e\\.g\\. (.+?), received (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/next/src/server/config.ts","lineNumber":1444,"sourceCode":"        const staticStaleTime = result.experimental.staleTimes?.static\n        defaultCacheLifeProfile.stale =\n          staticStaleTime ?? defaultConfig.experimental?.staleTimes?.static\n      }\n      if (defaultCacheLifeProfile.revalidate === undefined) {\n        defaultCacheLifeProfile.revalidate = defaultDefault.revalidate\n      }\n      if (defaultCacheLifeProfile.expire === undefined) {\n        defaultCacheLifeProfile.expire =\n          result.expireTime ?? defaultDefault.expire\n      }\n    }\n  }\n\n  if (result.cacheHandlers) {\n    const allowedHandlerNameRegex = /^[a-z-]+$/\n\n    if (typeof result.cacheHandlers !== 'object') {\n      throw new Error(\n        `Invalid \"cacheHandlers\" provided, expected an object e.g. { default: '/my-handler.js' }, received ${JSON.stringify(result.cacheHandlers)}`\n      )\n    }\n\n    const handlerKeys = Object.keys(result.cacheHandlers)\n    const invalidHandlerItems: Array<{ key: string; reason: string }> = []\n\n    for (const key of handlerKeys) {\n      if (key === 'private') {\n        invalidHandlerItems.push({\n          key,\n          reason:\n            'The cache handler for \"use cache: private\" cannot be customized.',\n        })\n      } else if (!allowedHandlerNameRegex.test(key)) {\n        invalidHandlerItems.push({\n          key,\n          reason: 'key must only use characters a-z and -',","sourceCodeStart":1426,"sourceCodeEnd":1462,"githubUrl":"https://github.com/vercel/next.js/blob/0ae8c72462952df163f1b1e0726641bc5b40dc93/packages/next/src/server/config.ts#L1426-L1462","documentation":"Thrown at config.ts:1443 when `cacheHandlers` is provided but `typeof result.cacheHandlers !== 'object'`. `cacheHandlers` maps cache-handler names to module paths (e.g. `{ default: '/my-handler.js' }`). Arrays are objects in JS and would pass this check but be caught by downstream key validation; non-object primitives (string, number, boolean) fail here.","triggerScenarios":"`cacheHandlers: '/my-handler.js'` (string); `cacheHandlers: ['default']` (array — passes here but fails key validation); `cacheHandlers: 42`.","commonSituations":"Misreading the option as a path string; migrating from an older array-based custom-handler config.","solutions":["Provide `cacheHandlers` as an object mapping handler names to resolved file paths.","Remove the `cacheHandlers` key if you are not customizing cache handlers."],"exampleFix":"// before\nmodule.exports = { cacheHandlers: '/my-handler.js' }\n// after\nmodule.exports = { cacheHandlers: { default: '/my-handler.js' } }","handlingStrategy":"type-guard","validationCode":"if (cacheHandlers !== undefined && (typeof cacheHandlers !== 'object' || Array.isArray(cacheHandlers))) {\n  throw new Error('cacheHandlers must be a plain object');\n}","typeGuard":"function isHandlerMap(x: unknown): x is Record<string, string> {\n  return typeof x === 'object' && x !== null && !Array.isArray(x);\n}","tryCatchPattern":null,"preventionTips":["Provide `cacheHandlers` as a `{ name: path }` object map.","Omit the key when not customizing handlers."],"tags":["config","cache","type-error"],"analyzedSha":"0ae8c72462952df163f1b1e0726641bc5b40dc93","analyzedAt":"2026-08-06T19:44:29.143Z","schemaVersion":2},"datasetVersion":"2026-08-07T02:17:10.218Z"}