angular/angular-cli · warning

The best practices guide at '${guidePath}' is larger than 1M

Error message

The best practices guide at '${guidePath}' is larger than 1MB (${stats.size} bytes). This is unexpected and the file will not be read. Falling back to the bundled guide.

What it means

The Angular CLI MCP best-practices tool looks for a version-specific guide referenced in the installed @angular/core package's 'angular.bestPractices' metadata. Before reading that file it stats it, and if the file exceeds 1MB it refuses to read it (a sanity check against corrupted or abnormally large files) and logs this warning, falling back to the guide bundled with the CLI.

Source

Thrown at packages/angular/cli/src/commands/mcp/tools/best-practices.ts:166

      // Ensure the resolved guide path is within the package boundary.
      // Uses path.relative to create a cross-platform, case-insensitive check.
      // If the relative path starts with '..' or is absolute, it is a traversal attempt.
      const relativePath = relative(packageDirectory, guidePath);
      if (relativePath.startsWith('..') || isAbsolute(relativePath)) {
        logger.warn(
          `Detected a potential path traversal attempt in '${pkgJsonPath}'. ` +
            `The path '${bestPracticesInfo.path}' escapes the package boundary. ` +
            'Falling back to the bundled guide.',
        );

        return undefined;
      }

      // Check the file size to prevent reading a very large file.
      const stats = await stat(guidePath);
      if (stats.size > 1024 * 1024) {
        // 1MB
        logger.warn(
          `The best practices guide at '${guidePath}' is larger than 1MB (${stats.size} bytes). ` +
            'This is unexpected and the file will not be read. Falling back to the bundled guide.',
        );

        return undefined;
      }

      const content = await readFile(guidePath, 'utf-8');
      const source = `framework version ${pkgJson.version}`;

      return { content, source };
    } else {
      logger.warn(
        `Did not find valid 'angular.bestPractices' metadata in '${pkgJsonPath}'. ` +
          'Falling back to the bundled guide.',
      );
    }
  } catch (e) {

View on GitHub (pinned to bb72145f9a)

Solutions

1. Reinstall @angular/core (delete node_modules and package-lock.json, then npm install) to restore the intact guide file.
2. Check the file size at the guidePath shown in the warning (find 'angular.bestPractices' in node_modules/@angular/core/package.json) and inspect why it is oversized.
3. Ignore the warning if acceptable: the CLI automatically falls back to its bundled best-practices guide.
4. If using a forked/patched Angular build, keep the best-practices markdown file under 1MB.

Example fix

// before: oversized or corrupted guide in node_modules/@angular/core
// after:
rm -rf node_modules package-lock.json
npm install

import { stat } from 'node:fs/promises';
const meta = pkgJson.angular?.bestPractices;
if (meta?.path) {
  const guidePath = resolve(pkgDir, meta.path);
  const stats = await stat(guidePath);
  if (stats.size > 1024 * 1024) console.warn('Guide oversized; bundled guide will be used');
}

function hasValidGuideMeta(pkg: unknown): pkg is { angular: { bestPractices: { path: string } } } {
  const m = (pkg as any)?.angular?.bestPractices;
  return !!m && typeof m.path === 'string' && m.path.length > 0;
}

try {
  const guide = await loadGuide(guidePath);
} catch (err) {
  logger.warn(`Guide load failed (${err}); using bundled guide`);
  guide = bundledGuide;
}

When it happens

Trigger: Calling the MCP best-practices tool when the installed @angular/core package declares an 'angular.bestPractices' file whose size, per stat(), is greater than 1024*1024 bytes; getVersionSpecificBestPractices then returns undefined and the bundled guide is used.

Common situations: A corrupted or tampered @angular/core installation (e.g., interrupted npm install, patched node_modules, pnpm store corruption) where the guide file ballooned past 1MB; custom forked Angular builds that ship an oversized guide.

Related errors

• Failed to read or parse version-specific best practices refe
• Did not find valid 'angular.bestPractices' metadata in '${pk
• Access denied: path '${path}' is outside allowed roots.
• Workspace path is outside the allowed MCP roots: ${workspace
• Failed to access path: ${fileOrDirPath}

AI-assisted analysis of angular/angular-cli@bb72145f9a (2026-08-30). Data as JSON: /api/errors/24b6e28f9a1267fd. Report an issue: GitHub.