{"record":{"id":"37944e3130bca9e9","repo":"angular/angular-cli","slug":"failed-to-read-or-parse-version-specific-best-prac","errorCode":null,"errorMessage":"Failed to read or parse version-specific best practices referenced in '${pkgJsonPath}': ${e instanceof Error ? e.message : e}. Falling back to the bundled guide.","messagePattern":"Failed to read or parse version-specific best practices referenced in '(.+?)': (.+?)\\. Falling back to the bundled guide\\.","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"packages/angular/cli/src/commands/mcp/tools/best-practices.ts","lineNumber":185,"sourceCode":"          `The best practices guide at '${guidePath}' is larger than 1MB (${stats.size} bytes). ` +\n            'This is unexpected and the file will not be read. Falling back to the bundled guide.',\n        );\n\n        return undefined;\n      }\n\n      const content = await readFile(guidePath, 'utf-8');\n      const source = `framework version ${pkgJson.version}`;\n\n      return { content, source };\n    } else {\n      logger.warn(\n        `Did not find valid 'angular.bestPractices' metadata in '${pkgJsonPath}'. ` +\n          'Falling back to the bundled guide.',\n      );\n    }\n  } catch (e) {\n    logger.warn(\n      `Failed to read or parse version-specific best practices referenced in '${pkgJsonPath}': ${\n        e instanceof Error ? e.message : e\n      }. Falling back to the bundled guide.`,\n    );\n  }\n\n  return undefined;\n}\n\n/**\n * Creates the handler function for the `get_best_practices` tool.\n * The handler orchestrates the process of first attempting to get a version-specific guide\n * and then falling back to the bundled guide if necessary.\n * @param context The MCP tool context, containing the logger.\n * @returns An async function that serves as the tool's executor.\n */\nfunction createBestPracticesHandler({ logger, server }: McpToolContext) {\n  let bundledBestPractices: Promise<string>;","sourceCodeStart":167,"sourceCodeEnd":203,"githubUrl":"https://github.com/angular/angular-cli/blob/bb72145f9ab45aee29f523236b3a25cd0813a841/packages/angular/cli/src/commands/mcp/tools/best-practices.ts#L167-L203","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Read the embedded `${e.message}` in the warning to identify the root cause (e.g., ENOENT, EACCES, JSON parse error).","Reinstall dependencies (rm -rf node_modules && npm install) to fix missing/corrupted files.","Fix file permissions on the project and node_modules directories.","Validate node_modules/@angular/core/package.json is parseable JSON if that is the failing point.","Rely on the bundled guide fallback if the version-specific guide is not essential."],"exampleFix":"// before: broken symlink / missing package\n// after:\nrm -rf node_modules package-lock.json\nnpm install","handlingStrategy":"try-catch","validationCode":"try {\n  await access(pkgJsonPath);\n  JSON.parse(await readFile(pkgJsonPath, 'utf-8'));\n} catch (e) {\n  console.warn('Framework package.json unreadable or invalid; version-specific guide unavailable:', e);\n}","typeGuard":"function isPackageJson(v: unknown): v is { name: string; version: string; angular?: unknown } {\n  return !!v && typeof v === 'object' && typeof (v as any).name === 'string' && typeof (v as any).version === 'string';\n}","tryCatchPattern":"try {\n  guide = await getVersionSpecificBestPractices(pkgJsonPath);\n} catch (e) {\n  logger.warn(`Version-specific guide failed: ${e instanceof Error ? e.message : e}. Using bundled guide.`);\n  guide = bundledGuide;\n}","preventionTips":["Keep node_modules intact: rerun npm install after crashes or disk-full events.","Check file permissions on the project directory, especially in Docker/WSL setups.","Validate package.json edits with a JSON linter.","Read the embedded error message in the warning to target the real cause."],"tags":["mcp","filesystem","parse-error","fallback","angular-cli"],"backgroundTag":"file-read-failed-fallback","analyzedSha":"bb72145f9ab45aee29f523236b3a25cd0813a841","analyzedAt":"2026-08-30T02:47:34.745Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}