Skip to content
Issue docs

Page weight over budget

Standardpage_weight_over_budgetIssue 190

What is this issue?

Page weight is the total size of everything a page downloads to load: the HTML, its stylesheets, scripts, fonts, images and video, as transferred over the network.

This check reports pages over 3 MB (3,072 KiB) in the PageSpeed lab load.

Why it matters

  • Bytes are time on mobile. Over a typical mobile connection, 3 MB takes several seconds to download before anything else is counted.
  • Bytes are money for some visitors, on metered data plans.
  • It is a budget, not a single fault. A heavy page is usually heavy for several reasons at once -- oversized images, unused JavaScript, autoplay video -- and the other checks on this page point at which.

Fixing it removes a standard-severity finding from the site's health score.

How to fix it

  1. Start with the largest files. The finding lists the five biggest requests; they are usually images or video.

  2. Compress and resize images, serve modern formats (WebP, AVIF) and correctly sized versions (see "Images larger than their displayed size").

  3. Do not autoplay video on load; show a poster image and load the video on click.

  4. Ship less JavaScript (see "Unused JavaScript").

  5. Lazy-load what is below the fold (see "Offscreen images loaded up front").

Examples

1. An uncompressed hero image

Fails -- 3.7 MB, of which a single 1.2 MB JPEG hero image.

Passes -- 1.4 MB: the hero as an 180 KB AVIF at the displayed size.

2. Autoplay background video

Fails -- 8.2 MB: a background video downloads in full on load.

Passes -- 0.9 MB: a poster image, with the video loaded only on desktop and after load.

How PixyScan detects this

  1. Chooses which pages to measure. After the crawl, PixyScan measures the homepage plus the pages your own site links to most, up to a per-scan budget (ten pages by default, at most fifty). Measuring every page would take hours and exhaust the PageSpeed Insights quota of the API key it runs under.

  2. Asks the PageSpeed Insights API about each of them, on mobile. This needs the Hobby plan or above and a PageSpeed Insights API key on the site or its workspace.

  3. Reads the Lighthouse audit total-byte-weight, which adds up the transfer size of every network request the page made while loading.

  4. Raises the issue when the total is more than 3 MB -- read as 3 MiB (3,145,728 bytes), the unit Lighthouse prints it in. A page of exactly 3 MB raises nothing. Lighthouse itself has no pass/fail bound for this audit; 3 MB is PixyScan's budget.

  5. Raises nothing on a page it did not measure. A page outside the sample, and a page whose measurement failed, are both reported as Not measured. Neither is treated as passing, and neither can fail this check.

What we store

Storage Level

Page Level

Database Table / Prisma Model

PagePerformance (page_performance), with the finding itself on audit_issues.details.

Fields Used

Field Type Description
strategy String mobile or desktop. Every number in the row belongs to one form factor.
fetchedAt DateTime When PageSpeed answered. "Measured three weeks ago" is not "not measured".
errorReason String? Why a sampled page still has no numbers. Null when the call succeeded.
audits Json? A compact summary of the Lighthouse audits the opportunity checks read: per audit its source (the Lighthouse audit id it was read from), score, numericValue, displayValue, itemCount, totals over every row (wastedBytes, wastedMs, blockingTime, mainThreadTime) and the five worst rows. Keyed by the classic Lighthouse audit id. Null when the response carried no audits.

On the finding (audit_issues.details): message, plus audit (total-byte-weight), totalBytes, thresholdBytes (3145728) and items (the five largest requests, each url and totalBytes).

Detection Dependencies

  • PageSpeed Insights API v5 (lighthouseResult.audits), mobile strategy
  • The PageSpeed plan feature (Hobby and above) and a PageSpeed Insights API key
  • The crawl's internal link graph, which decides which pages are sampled

Note

A page with no row was never measured. The pass samples the homepage plus the most-linked pages within a per-scan budget (default 10, at most 50), so most pages of a site have no page_performance row at all. That is the normal state, it is drawn as Not measured, and this check cannot be raised against it.

A row whose metric columns are all null with an errorReason set is a different state again: the page WAS sampled and the measurement failed. It is still never reported as passing.

Further reading