mastra-ai/mastra · error

INVALID_TSCONFIG

INVALID_TSCONFIG

Error message

INVALID_TSCONFIG

What it means

The lint rule checks that tsconfig.json compilerOptions use either moduleResolution "bundler" or module "CommonJS", which are the configurations Mastra supports for building/loading user code. Any other combination (e.g. ESM-style module without bundler resolution) throws this project-scope error.

Source

Thrown at packages/cli/src/commands/lint/rules/tsConfigRule.ts:40

    if (!tsConfig) {
      return [
        {
          code: 'MISSING_TSCONFIG',
          severity: 'warning',
          scope: 'project',
          message: 'No tsconfig.json found. Mastra projects should include a TypeScript config.',
          fix: 'Add a tsconfig.json file. See https://mastra.ai/en/docs/getting-started/installation#initialize-typescript',
        },
      ];
    }

    const { module, moduleResolution } = tsConfig.compilerOptions || {};

    const isValidConfig = moduleResolution === 'bundler' || module === 'CommonJS';
    if (!isValidConfig) {
      return [
        {
          code: 'INVALID_TSCONFIG',
          severity: 'error',
          scope: 'project',
          message:
            'tsconfig.json must set either compilerOptions.moduleResolution to "bundler" or compilerOptions.module to "CommonJS".',
          fix: 'Update tsconfig.json with either { "compilerOptions": { "moduleResolution": "bundler" } } or { "compilerOptions": { "module": "CommonJS" } }. See https://mastra.ai/en/docs/getting-started/installation#initialize-typescript',
        },
      ];
    }

    return [];
  },
};

View on GitHub (pinned to 75dd419e61)

Solutions

1. Set compilerOptions.moduleResolution to "bundler" in tsconfig.json
2. Alternatively set compilerOptions.module to "CommonJS"
3. Run `mastra init` to regenerate a known-good tsconfig

Example fix

// before
{ "compilerOptions": { "module": "ESNext", "moduleResolution": "node" } }
// after
{ "compilerOptions": { "module": "ESNext", "moduleResolution": "bundler" } }

const tsconfig = JSON.parse(readFileSync(join(rootDir, 'tsconfig.json'), 'utf-8'));
const { module, moduleResolution } = tsconfig.compilerOptions ?? {};
if (moduleResolution !== 'bundler' && module !== 'CommonJS') {
  throw new Error('Set compilerOptions.moduleResolution="bundler" or module="CommonJS"');
}

const isMastraCompatible = (c: unknown): c is { compilerOptions?: { module?: string; moduleResolution?: string } } =>
  typeof c === 'object' && c !== null;
const isValid = (c: { compilerOptions?: { module?: string; moduleResolution?: string } }) =>
  c.compilerOptions?.moduleResolution === 'bundler' || c.compilerOptions?.module === 'CommonJS';

try {
  await mastraLint();
} catch (e) {
  if ((e as Error).message.includes('INVALID_TSCONFIG')) {
    console.error('Fix tsconfig compilerOptions: moduleResolution=bundler or module=CommonJS');
  } else throw e;
}

When it happens

Trigger: `mastra lint` finds a tsconfig.json whose compilerOptions.module/moduleResolution are missing or set to unsupported values (e.g. module: ESNext with moduleResolution: node).

Common situations: Projects scaffolded for ESM with `moduleResolution: node16`/`nodenext`; tsconfig created by `tsc --init` defaults; migrating a Mastra project from an older template.

Related errors

• MISSING_TSCONFIG
• Okta domain is required. Provide it in the options or set OK
• Okta API token is required for RBAC. Provide it in the optio
• Supabase URL and anon key are required, please provide them
• WorkOS API key and client ID are required. Provide them in t

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