Lighthouse was measuring the wrong page

I was hardening the Lighthouse gate on devfrs.com: move from warn to error, with SEO at 100. The first result came back odd.

route	perf	seo
/	75	100
/en/	38	100
/projeto/<slug>/	79	100

Thirty-eight. On near-identical pages, from the same build. And SEO — the thing I was actually changing — had hit 100, so the temptation was to celebrate and write performance off as noise.

The symptom that didn’t add up

Alongside the scores came a link-text failure: a link reading “Learn more” pointing at docs.astro.build. I have no such link anywhere. I searched the whole dist/:

grep -r "docs.astro.build" dist/

Nothing. The link didn’t exist in what I had built — but it existed on the page Lighthouse measured. There’s only one explanation: the page it measured wasn’t mine.

The cause

That “Learn more” belongs to the Astro dev toolbar, which only exists in dev mode. Lighthouse had audited the dev server, not dist/.

The reason is trivial, which is exactly why it slips through: I had npm run dev open on port 4321, and my test server tried to bind the same port. It failed, the process died quietly, and Lighthouse found someone answering on 4321. It happily measured that.

Perf 62 for a site in dev mode is a perfectly plausible number. That’s the problem. An error that screams is cheap; an error that hands you a believable number costs hours.

The two fixes

The first is obvious: a separate port for the gate. The second is the one that matters:

server.on("error", (err) => {
  if (err.code === "EADDRINUSE") {
    console.error(
      `[serve-dist] port ${PORT} is already in use — aborting.\n` +
        `Another process would answer instead of dist/, and Lighthouse would measure the wrong page.`,
    );
  }
  process.exit(1);
});

Fail loud instead of quiet. If the port is taken, nothing gets measured — better to break the gate with a clear message than to publish a made-up number.

With the right server and a median of three runs, the numbers became 95 and 99. Only then was it worth locking the gate down.

What I take from this

Before trusting a measurement, it’s worth asking what it would report if it were broken. If the answer is “a number close to the right one”, you’re missing a signal — not precision.