{"record":{"id":"d6159d85b4c998b7","repo":"mastra-ai/mastra","slug":"next-missing-server-external-packages","errorCode":"NEXT_MISSING_SERVER_EXTERNAL_PACKAGES","errorMessage":"NEXT_MISSING_SERVER_EXTERNAL_PACKAGES","messagePattern":"NEXT_MISSING_SERVER_EXTERNAL_PACKAGES","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/cli/src/commands/lint/rules/nextConfigRule.ts","lineNumber":206,"sourceCode":"    return true;\n  } catch {\n    return false;\n  }\n}\n\nexport const nextConfigRule: LintRule = {\n  name: 'next-config',\n  description: 'Checks if Next.js config is properly configured for Mastra packages',\n  async run(context: LintContext): Promise<LintIssue[]> {\n    if (!isNextJsProject(context.rootDir)) {\n      return [];\n    }\n\n    const nextConfig = readNextConfig(context.rootDir);\n    if (!nextConfig) {\n      return [\n        {\n          code: 'NEXT_MISSING_SERVER_EXTERNAL_PACKAGES',\n          severity: 'error',\n          scope: 'project',\n          message: 'next.config.js could not be parsed for serverExternalPackages.',\n          fix: 'Ensure next.config.js exports a plain object and includes serverExternalPackages: [\"@mastra/*\"].',\n        },\n      ];\n    }\n\n    const serverExternals = nextConfig.serverExternalPackages || [];\n    const hasMastraExternals = serverExternals.some(\n      (pkg: string) => pkg === '@mastra/*' || pkg === '@mastra/core' || pkg.startsWith('@mastra/'),\n    );\n\n    if (!hasMastraExternals) {\n      return [\n        {\n          code: 'NEXT_MISSING_SERVER_EXTERNAL_PACKAGES',\n          severity: 'error',","sourceCodeStart":188,"sourceCodeEnd":224,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/cli/src/commands/lint/rules/nextConfigRule.ts#L188-L224","documentation":"A lint rule for Next.js projects that could not read/parse next.config.js at all to check serverExternalPackages. Because the config can't be evaluated, the rule reports the missing-packages error to flag that Mastra packages may be bundled incorrectly by Next.","triggerScenarios":"Running `mastra lint` in a Next.js project where readNextConfig returns null — no next.config.js found, or the config isn't exportable as a plain object (e.g. uses ESM default export in a CJS-parsed file, functions, or third-party wrappers).","commonSituations":"Next.js 13/14 projects without serverExternalPackages configured, next.config.mjs/ts variants the reader can't load, or configs wrapped with defineConfig-style helpers.","solutions":["Ensure a next.config.js exists at the project root and exports a plain object.","Add serverExternalPackages: ['@mastra/*'] to the config.","If you use next.config.mjs/ts, verify the lint rule supports that filename or convert to next.config.js.","Re-run `mastra lint` after fixing the config."],"exampleFix":"// before (next.config.js)\nmodule.exports = {};\n// after\nmodule.exports = { serverExternalPackages: ['@mastra/*'] };","handlingStrategy":"validation","validationCode":"import fs from 'node:fs';\nif (!fs.existsSync('next.config.js') && !fs.existsSync('next.config.mjs')) {\n  console.warn('Create next.config.js exporting a plain object with serverExternalPackages: [\"@mastra/*\"]');\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Keep next.config.js as a plain-object export that the tooling can parse.","Add serverExternalPackages when first integrating Mastra with Next.js.","Verify the config file name/format matches what `mastra lint` supports."],"tags":["lint","nextjs","configuration","bundler"],"backgroundTag":"next-config-misconfigured","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}