mastra-ai/mastra · warning

MISSING_TSCONFIG

MISSING_TSCONFIG

Error message

MISSING_TSCONFIG

What it means

The `mastra lint` tsconfig rule warns when no tsconfig.json can be found or parsed in the project root. Mastra relies on TypeScript configuration to compile scorers, workflows, and tools correctly, so a missing tsconfig is flagged as a project-scope warning. readTsConfig returned falsy, meaning the file is absent or unreadable.

Source

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

  const tsConfigPath = join(dir, 'tsconfig.json');
  try {
    const tsConfigContent = readFileSync(tsConfigPath, 'utf-8');
    const cleanTsConfigContent = stripJsonComments(tsConfigContent);
    return JSON.parse(cleanTsConfigContent);
  } catch {
    return null;
  }
}

export const tsConfigRule: LintRule = {
  name: 'ts-config',
  description: 'Checks if TypeScript config is properly configured for Mastra packages',
  async run(context: LintContext): Promise<LintIssue[]> {
    const tsConfig = readTsConfig(context.rootDir);
    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:

View on GitHub (pinned to 75dd419e61)

Solutions

1. Add a tsconfig.json to the project root
2. Run `mastra init` to scaffold the recommended TypeScript setup
3. Run lint from the directory that actually contains tsconfig.json

Example fix

// before
(no tsconfig.json in project root)
// after
// tsconfig.json
{ "compilerOptions": { "module": "CommonJS", "target": "ES2022" }, "include": ["src"] }

import { existsSync } from 'node:fs';
import { join } from 'node:path';
if (!existsSync(join(rootDir, 'tsconfig.json'))) {
  throw new Error('tsconfig.json missing in project root — run `mastra init` first');
}

const hasTsConfig = (rootDir: string): boolean =>
  existsSync(join(rootDir, 'tsconfig.json'));

try {
  await lintProject();
} catch (e) {
  if ((e as Error).message.includes('MISSING_TSCONFIG')) {
    console.warn('No tsconfig.json found; skipping TypeScript lint checks.');
  } else throw e;
}

When it happens

Trigger: Running `mastra lint` in a directory where context.rootDir contains no tsconfig.json, or where readTsConfig fails to parse/find one.

Common situations: Fresh JavaScript-only projects initialized without `mastra init`; running lint from the wrong directory; tsconfig.json named differently (e.g. tsconfig.build.json); repo where tsconfig lives in a subdirectory.

Related errors

• INVALID_TSCONFIG
• Project not found: ${wanted}
• No project specified. Pass --project <name|slug|id>, set MAS
• Could not determine project name from package.json. Use --pr
• No linked project found. Deploy first with `mastra server de

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