mastra-ai/mastra · error

NEXT_MISSING_SERVER_EXTERNAL_PACKAGES

NEXT_MISSING_SERVER_EXTERNAL_PACKAGES

Error message

NEXT_MISSING_SERVER_EXTERNAL_PACKAGES

What it means

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.

Source

Thrown at packages/cli/src/commands/lint/rules/nextConfigRule.ts:206

    return true;
  } catch {
    return false;
  }
}

export const nextConfigRule: LintRule = {
  name: 'next-config',
  description: 'Checks if Next.js config is properly configured for Mastra packages',
  async run(context: LintContext): Promise<LintIssue[]> {
    if (!isNextJsProject(context.rootDir)) {
      return [];
    }

    const nextConfig = readNextConfig(context.rootDir);
    if (!nextConfig) {
      return [
        {
          code: 'NEXT_MISSING_SERVER_EXTERNAL_PACKAGES',
          severity: 'error',
          scope: 'project',
          message: 'next.config.js could not be parsed for serverExternalPackages.',
          fix: 'Ensure next.config.js exports a plain object and includes serverExternalPackages: ["@mastra/*"].',
        },
      ];
    }

    const serverExternals = nextConfig.serverExternalPackages || [];
    const hasMastraExternals = serverExternals.some(
      (pkg: string) => pkg === '@mastra/*' || pkg === '@mastra/core' || pkg.startsWith('@mastra/'),
    );

    if (!hasMastraExternals) {
      return [
        {
          code: 'NEXT_MISSING_SERVER_EXTERNAL_PACKAGES',
          severity: 'error',

View on GitHub (pinned to 75dd419e61)

Solutions

1. Ensure a next.config.js exists at the project root and exports a plain object.
2. Add serverExternalPackages: ['@mastra/*'] to the config.
3. If you use next.config.mjs/ts, verify the lint rule supports that filename or convert to next.config.js.
4. Re-run `mastra lint` after fixing the config.

Example fix

// before (next.config.js)
module.exports = {};
// after
module.exports = { serverExternalPackages: ['@mastra/*'] };

import fs from 'node:fs';
if (!fs.existsSync('next.config.js') && !fs.existsSync('next.config.mjs')) {
  console.warn('Create next.config.js exporting a plain object with serverExternalPackages: ["@mastra/*"]');
}

When it happens

Trigger: 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).

Common situations: 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.

Related errors

• MISSING_MASTRA_CORE
• AcpAgent does not support resuming suspended generate calls
• ACP prompt stopped before completing: ${response.stopReason}
• Auth0 domain and audience are required, please provide them
• Cookie password must be at least 32 characters for SSO. Set

AI-assisted analysis of mastra-ai/mastra@75dd419e61 (2026-08-30). Data as JSON: /api/errors/d6159d85b4c998b7. Report an issue: GitHub.