angular/angular-cli · warning

Failed to read or parse version-specific best practices refe

Error message

Failed to read or parse version-specific best practices referenced in '${pkgJsonPath}': ${e instanceof Error ? e.message : e}. Falling back to the bundled guide.

What it means

The entire attempt to load a version-specific best-practices guide (reading the framework package.json, resolving the guide path, and reading the file) is wrapped in try/catch. Any thrown error during that process — unreadable file, invalid JSON, ENOENT, permission issues — is caught, logged as this warning with the underlying message, and the CLI falls back to the bundled guide.

Source

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

          `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
 * and then falling back to the bundled guide if necessary.
 * @param context The MCP tool context, containing the logger.
 * @returns An async function that serves as the tool's executor.
 */
function createBestPracticesHandler({ logger, server }: McpToolContext) {
  let bundledBestPractices: Promise<string>;

View on GitHub (pinned to bb72145f9a)

Solutions

1. Read the embedded `${e.message}` in the warning to identify the root cause (e.g., ENOENT, EACCES, JSON parse error).
2. Reinstall dependencies (rm -rf node_modules && npm install) to fix missing/corrupted files.
3. Fix file permissions on the project and node_modules directories.
4. Validate node_modules/@angular/core/package.json is parseable JSON if that is the failing point.
5. Rely on the bundled guide fallback if the version-specific guide is not essential.

Example fix

// before: broken symlink / missing package
// after:
rm -rf node_modules package-lock.json
npm install

try {
  await access(pkgJsonPath);
  JSON.parse(await readFile(pkgJsonPath, 'utf-8'));
} catch (e) {
  console.warn('Framework package.json unreadable or invalid; version-specific guide unavailable:', e);
}

function isPackageJson(v: unknown): v is { name: string; version: string; angular?: unknown } {
  return !!v && typeof v === 'object' && typeof (v as any).name === 'string' && typeof (v as any).version === 'string';
}

try {
  guide = await getVersionSpecificBestPractices(pkgJsonPath);
} catch (e) {
  logger.warn(`Version-specific guide failed: ${e instanceof Error ? e.message : e}. Using bundled guide.`);
  guide = bundledGuide;
}

When it happens

Trigger: getVersionSpecificBestPractices throws anywhere inside its try block: stat/readFile failures on the guide path, JSON.parse failures on package.json, or malformed metadata structures that throw when accessed.

Common situations: Broken node_modules (missing @angular/core), permission-restricted project directories, a manually edited package.json with invalid JSON, symlinked or virtualized filesystems (Docker/WSL) where the guide path is unreadable.

Related errors

• The best practices guide at '${guidePath}' is larger than 1M
• 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/37944e3130bca9e9. Report an issue: GitHub.