angular/angular · warning

2952

2952

Error message

${imgDirectiveDetails(dir.ngSrc)} the aspect ratio of the image does not match the aspect ratio indicated by the width and height attributes. 
Intrinsic image size: ${intrinsicWidth}w x ${intrinsicHeight}h (aspect-ratio: ${round(intrinsicAspectRatio)}). 
Supplied width and height attributes: ${suppliedWidth}w x ${suppliedHeight}h (aspect-ratio: ${round(suppliedAspectRatio)}). 
To fix this, update the width and height attributes.

What it means

After an NgOptimizedImage loads, dev-mode validators compare the aspect ratio implied by the width/height attributes against the image file's intrinsic ratio (naturalWidth/naturalHeight). If they diverge by more than ASPECT_RATIO_TOLERANCE (0.1), warning NG02952 (INVALID_INPUT) fires with both ratios printed and asks you to correct the attributes. Wrong attribute ratios reserve the wrong layout box and cause layout shift (CLS) before the image loads.

Source

Thrown at packages/common/src/directives/ng_optimized_image/ng_optimized_image.ts:1126

    const intrinsicAspectRatio = intrinsicWidth / intrinsicHeight;

    const suppliedWidth = dir.width!;
    const suppliedHeight = dir.height!;
    const suppliedAspectRatio = suppliedWidth / suppliedHeight;

    // Tolerance is used to account for the impact of subpixel rendering.
    // Due to subpixel rendering, the rendered, intrinsic, and supplied
    // aspect ratios of a correctly configured image may not exactly match.
    // For example, a `width=4030 height=3020` image might have a rendered
    // size of "1062w, 796.48h". (An aspect ratio of 1.334... vs. 1.333...)
    const inaccurateDimensions =
      Math.abs(suppliedAspectRatio - intrinsicAspectRatio) > ASPECT_RATIO_TOLERANCE;
    const stylingDistortion =
      nonZeroRenderedDimensions &&
      Math.abs(intrinsicAspectRatio - renderedAspectRatio) > ASPECT_RATIO_TOLERANCE;

    if (inaccurateDimensions) {
      console.warn(
        formatRuntimeError(
          RuntimeErrorCode.INVALID_INPUT,
          `${imgDirectiveDetails(dir.ngSrc)} the aspect ratio of the image does not match ` +
            `the aspect ratio indicated by the width and height attributes. ` +
            `\nIntrinsic image size: ${intrinsicWidth}w x ${intrinsicHeight}h ` +
            `(aspect-ratio: ${round(
              intrinsicAspectRatio,
            )}). \nSupplied width and height attributes: ` +
            `${suppliedWidth}w x ${suppliedHeight}h (aspect-ratio: ${round(
              suppliedAspectRatio,
            )}). ` +
            `\nTo fix this, update the width and height attributes.`,
        ),
      );
    } else if (stylingDistortion) {
      console.warn(
        formatRuntimeError(
          RuntimeErrorCode.INVALID_INPUT,

View on GitHub (pinned to 51cb07e980)

Solutions

1. Update the width/height attributes so their ratio matches the intrinsic image (e.g., 800x600 asset -> width="800" height="600" or width="400" height="300")
2. If the display box must differ from the file's ratio, fix the asset (crop it) so the attributes tell the truth
3. Generate the attributes from image metadata in the build (e.g., a CI step comparing template dimensions against files)

Example fix

<!-- before: file is 800x600 (4:3), attributes claim 1:1 -->
<img ngSrc="photo.jpg" width="400" height="400" />

<!-- after -->
<img ngSrc="photo.jpg" width="400" height="300" />

function matchesIntrinsicRatio(
  w: number, h: number, naturalW: number, naturalH: number, tol = 0.1,
) {
  return Math.abs(w / h - naturalW / naturalH) <= tol;
}
// CI check: compare template attributes against the actual asset
if (!matchesIntrinsicRatio(400, 400, 800, 600)) {
  throw new Error('width/height attributes do not match the asset ratio');
}

When it happens

Trigger: `<img ngSrc="photo.jpg" width="400" height="400">` where photo.jpg is intrinsically 800x600; the check runs in dev mode once the image has loaded and natural dimensions are known.

Common situations: Hard-coded width/height copied from design mockups while the asset changed; CMS images whose ratio varies per item; swapping image assets without updating templates.

Related errors

• NG02952
• REQUIRED_INPUT_MISSING
• 2959
• 2964
• INVALID_INPUT

AI-assisted analysis of angular/angular@51cb07e980 (2026-08-22). Data as JSON: /api/errors/7a66a09bc4179c40. Report an issue: GitHub.