angular/angular-cli · warning

Did not find valid 'angular.bestPractices' metadata in '${pk

Error message

Did not find valid 'angular.bestPractices' metadata in '${pkgJsonPath}'. Falling back to the bundled guide.

What it means

When the CLI reads the installed @angular/core package.json looking for valid 'angular.bestPractices' metadata (a path to a version-specific guide), the metadata is missing or malformed. The CLI logs this warning and falls back to its bundled best-practices guide instead of failing.

Source

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

      // 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) {
    logger.warn(
      `Failed to read or parse version-specific best practices referenced in '${pkgJsonPath}': ${
        e instanceof Error ? e.message : e
      }. Falling back to the bundled guide.`,
    );
  }

  return undefined;
}

/**
 * Creates the handler function for the `get_best_practices` tool.
 * The handler orchestrates the process of first attempting to get a version-specific guide

View on GitHub (pinned to bb72145f9a)

Solutions

1. Upgrade @angular/core to a version that ships valid 'angular.bestPractices' metadata.
2. Verify node_modules/@angular/core/package.json contains an 'angular' object with a valid 'bestPractices' field; reinstall if stripped.
3. Confirm your registry/mirror (e.g., Verdaccio, Nexus) doesn't strip custom package.json fields.
4. Accept the fallback: the bundled guide still provides best practices for the tool.

Example fix

// before: node_modules/@angular/core/package.json without metadata
{ "name": "@angular/core", "version": "17.0.0" }
// after: upgrade so the metadata exists
{ "name": "@angular/core", "version": "20.0.0", "angular": { "bestPractices": { "path": "./guides/best-practices.md" } } }

const pkg = JSON.parse(await readFile('node_modules/@angular/core/package.json', 'utf-8'));
const bp = pkg.angular?.bestPractices;
if (!bp) console.warn('No angular.bestPractices metadata; CLI will use bundled guide');

function hasBestPracticesMeta(pkg: any): boolean {
  return typeof pkg?.angular?.bestPractices === 'object' && pkg.angular.bestPractices !== null;
}

try {
  guide = await getVersionSpecificBestPractices(...);
} catch {
  guide = bundledGuide; // metadata missing -> bundled fallback
}

When it happens

Trigger: getVersionSpecificBestPractices resolves the package.json of the installed Angular framework, finds no valid 'angular.bestPractices' entry (missing, wrong type, or structurally invalid), and takes the else branch that logs this warning.

Common situations: Running against an older Angular version that predates the bestPractices metadata field; packages published by registries/mirrors that strip custom fields; third-party or patched @angular/core builds.

Related errors

• The best practices guide at '${guidePath}' is larger than 1M
• Failed to read or parse version-specific best practices refe
• Workspace path is outside the allowed MCP roots: ${workspace
• Watch mode execution (serve target or watch option) is not y
• Workspace path is outside the allowed MCP roots: ${workspace

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