DEV Community: Liam

9,104 rows in, 5,000 out: the silent cap that made my dashboard lie

Liam — Sun, 02 Aug 2026 15:22:07 +0000

I sat down to add a small thing to an internal dashboard: a NEW badge on a search-rank table, so you could tell "this keyword just broke into the rankings" from "this keyword didn't move." An afternoon of work.

Then I went looking for the data to base it on, and found that the table had been reading 55% of its own rows for the last four days, without saying so.

What was actually happening

The page pulled raw daily rows through a generic query endpoint and folded them in the browser. The request asked for 8,000 rows. The server had this:

_MAX_LIMIT = 5000
...
limit = max(1, min(limit, _MAX_LIMIT))

min(). Not a 400, not a warning header, not a truncated: true in the response body. It hands you 5,000 rows and a 200 and lets you assume that's everything.

The table had 9,104 rows — 9 days of collection at roughly 1,000 keywords a day. So 4,104 rows never arrived. And because the query carried no ORDER BY, which 5,000 arrived was entirely up to the planner.

Both halves are needed for it to really hurt. A cap with a deterministic sort truncates the tail, which is at least a bug you can reason about: you know you're missing the oldest, or the lowest-ranked, or whatever your sort key implies. A cap with no sort hands you an arbitrary sample and presents it as the whole population.

Why nobody noticed

The dashboard didn't render an error. It rendered a dash.

Rank change is computed by comparing the current window against the previous one. If the previous window's rows happen to be the ones that fell off the truncated edge, there's nothing to compare against, so the cell shows —. Which is exactly what a keyword whose rank didn't change looks like.

That's the part worth stealing from this: the failure didn't surface as missing data, it surfaced as "no change." Absence and zero rendered identically, and one of them is boring enough that your eye slides right over it.

There's a second reason it stayed hidden, and it's the one I keep thinking about. At 1,000 rows a day, this code was correct on launch day. Day 4 fits under the cap. Day 5 fits. Day 6 crosses 5,000 and the dashboard starts lying, a little more each morning. There is no deploy to correlate it with, no error rate to alert on, no bad commit to bisect to. The bug arrives on a schedule you set months earlier and forgot about.

The fix is boring, and the payload got smaller

Stop shipping raw daily rows to the browser at all. Fold the window in SQL. Postgres DISTINCT ON gives you the latest measurement per key in a single pass:

WITH cur AS (
  SELECT DISTINCT ON (kind, keyword)
         kind, keyword, day::date AS day, rank
    FROM naver_site_rank
   WHERE day::date > %s AND day::date <= %s      -- current window
   ORDER BY kind, keyword, day::date DESC
), prv AS (
  SELECT DISTINCT ON (kind, keyword)
         kind, keyword, day::date AS prev_day, rank AS prev_rank
    FROM naver_site_rank
   WHERE day::date > %s AND day::date <= %s      -- previous window
   ORDER BY kind, keyword, day::date DESC
)
SELECT c.*, p.prev_rank, p.prev_day,
       (p.prev_day IS NOT NULL) AS measured_prev
  FROM cur c
  LEFT JOIN prv p ON p.kind = c.kind AND p.keyword = c.keyword

(Windows are half-open — (from, to] — so the current and previous window can't both claim the boundary day.)

One row per key means the response size is bounded by how many keywords exist, not by how long you've been collecting. About 1,300 rows and 275 KB, whether you ask for a week or a month or next year. That's smaller than the broken 5,000-row response, and it's complete.

The rule I wrote into the repo's guide afterward: if the row count grows with the date range, fold it on the server. Anything else is a cap waiting to be crossed, and you won't be watching on the day it happens.

The second bug, which was worse than the first

With real data finally reaching the page, I could compute the NEW badge. It came out wrong anyway.

The keyword sample rotates. There are 1,308 keywords total and the collector measures about 1,000 of them per day, so any given keyword is simply absent from some days. If you read absent as "wasn't ranking," every gap in the rotation becomes a triumphant new entry. On a weekly window that inflated NEW from 10 to 47.

So the state isn't a boolean, it's three-valued:

def _is_new(row, has_baseline):
    """Ranked now, and last window we LOOKED and it wasn't there."""
    if not has_baseline or not row["measured_prev"]:
        return False   # not measured is unknown, not "wasn't there"
    return row["rank"] is not None and row["rank_prev"] is None

it was ranked
it was measured, and it wasn't ranked
we didn't look

Only the middle one can produce a NEW. The third has to stay unknown, which the UI draws as ? rather than as an arrow.

has_baseline covers the degenerate case: if the previous window contains no measurements at all — pick "month" on day 9 of collection and it won't — then the honest answer isn't "everything is new," it's "can't compare." The page says that in words and draws no arrows at all.

I pulled that predicate into its own function specifically so I could pin it in a test. It's the kind of rule that gets quietly re-broken by the next person who thinks a NULL rank means rank zero.

Takeaways

A cap that returns 200 is a lie generator. If you clamp, say so in the response. {"truncated": true, "cap": 5000} costs you one key and saves someone a day.
LIMIT without ORDER BY is sampling, not truncation. The Postgres docs say it plainly: without an ORDER BY that constrains the rows into a unique order, you get "an unpredictable subset". Which is indistinguishable from complete data at the call site.
Watch for bugs whose trigger is a row count. They ship green and go red on their own schedule, long after the deploy that caused them.
Missing and zero are different values, and they must render differently. Every place you collapse them, you're choosing to make an unknown look like a measurement.

This is from an internal analytics dashboard I built to track a handful of my own sites — mostly Toolio, a set of small browser-based tools — which is how a rank table ended up growing by a thousand rows a day in the first place.

The checklist item that made 90 files permanently unfinished

Liam — Thu, 23 Jul 2026 23:00:00 +0000

I have a pipeline that generates document scaffolds — skeletons with blanks for a human to fill in. Every generated file looks roughly like this:

<!-- draft-stage: scaffold -->

## Hook
- [✏️ one line that stops the scroll]

## Caption
- [✏️ 1-2 sentences, facts only]

## Before you publish
- [ ] Zero `[✏️]` left → delete the `<!-- draft-stage: scaffold -->` line above

Two markers carry the state. [✏️] marks a blank nobody filled yet. The HTML comment marks "this file is still a skeleton." A dashboard reads both to decide whether a document is done:

SCAFFOLD_MARK = "<!-- draft-stage: scaffold -->"
PEN = "✏️"

def stage_of(path) -> str:
    text = path.read_text(encoding="utf-8")
    return "scaffold" if (SCAFFOLD_MARK in text or PEN in text) else "draft"

Simple enough. Read the file, look for either marker, done.

Except every single file came back scaffold. All 90 of them. Files that had been filled in weeks earlier, reviewed, and published still showed up as unfinished work.

The last line of the file

Look at the checklist again:

- [ ] Zero `[✏️]` left → delete the `<!-- draft-stage: scaffold -->` line above

That line — the one telling you how to mark the file complete — contains both markers verbatim. So the moment you follow the instruction and delete the HTML comment, stage_of() still finds [✏️]… in the sentence explaining that there should be no [✏️].

The exit condition was unsatisfiable. Not "hard to satisfy" — unsatisfiable, because the document could not describe its own completion criteria without violating them.

The generator wrote that line. Every file it produced was born permanently unfinished.

Why nobody noticed for weeks

This is the part I find more interesting than the bug.

The dashboard showed a big number of pending documents. That number never went down. And a number that never goes down stops being information — people stop reading it. When I finally asked why it was stuck, I'd already been ignoring it for a while, which is exactly what always-red signals train you to do.

The fix took one line. Rewrite the instruction so it describes the markers instead of containing them:

- [ ] No pencil slots left → delete the `draft-stage` comment at the top of the file

Re-running the check flipped 37 of 90 files from "unfinished" to "done" instantly. Nothing about those files changed. They had been done the whole time.

The general shape

This is in-band signaling: control information travelling in the same channel as the payload. Telephone networks hit it in the 1960s — the 2600 Hz tone that told a trunk line it was idle could be whistled into the handset by a person, and the network could not tell the difference between "the switch says this line is free" and "a human made that sound." Same class of problem, seventy years apart.

Once you have the shape in your head, you see it everywhere:

A log parser that greps for ERROR — and logs ERROR when it fails to parse a line.
A linter whose README documents the pattern it flags, and which is run over its own repo.
A test that asserts "no TODO in source" while its own source explains what a TODO is.
Markdown-based feature flags where the flag name appears in the docs describing the flag.

The common failure mode isn't that the marker is a bad choice. [✏️] is fine. It's that the same file serves two readers — a parser and a human — and the humans need to talk about the marker while the parser only knows how to find it.

What I'd do differently

Three options, roughly in order of how much I'd trust them:

1. Move state out of the payload. A sidecar file, frontmatter field, or database column means the prose can say whatever it wants. This is the real fix; the rest are mitigations.

2. Make the sentinel unspeakable. Pick something a human writing documentation would never type, and if you must mention it, mention it by name (the draft-stage comment) rather than by value. This is what I actually shipped, because the marker also has to be visually obvious in a rendered document — that was the whole point of using an emoji.

3. Exclude the region. Skip fenced code blocks, or everything after a  line. Works, but now you have two parsers that must agree, and the failure is silent when they drift.

There's a fourth option I want to flag because it's tempting and wrong: parse "smarter" — only count [✏️] when it's inside brackets at the start of a list item, etc. Every heuristic you add makes the rule harder to state, and a state machine you can't state in one sentence is one nobody can reason about. The bug came from a rule that was too clever by half already.

The check that would have caught it

The cheapest guard is a self-test on the generator, not the documents:

def test_generated_scaffold_can_be_completed():
    """A freshly generated file must be completable by following its own instructions."""
    text = build_scaffold(sample_item)
    # do what the instructions say: fill every slot, drop the marker
    filled = re.sub(r"\[✏️[^\]]*\]", "x", text).replace(SCAFFOLD_MARK, "")
    assert stage_of_text(filled) == "draft", "scaffold cannot be completed as instructed"

That test fails on the old template and passes on the new one. It encodes the property that actually matters — the exit condition is reachable — instead of testing the parser against inputs I thought of.

For context: the pipeline generates publishing copy for a set of small browser-based tools I build (toolio.pongvn.com), which is why the documents have slots for hooks and captions in the first place. The bug had nothing to do with the tools and everything to do with letting a document describe its own state — but it did mean a couple of months of "you have 90 things to do" that were, in fact, 37 things already done.

If you have a marker-based state machine anywhere, go check whether your docs mention the marker. It takes about thirty seconds and the answer is occasionally embarrassing.

The one-line bug that broke Open Graph cards on 836 pages

Liam — Thu, 23 Jul 2026 02:17:49 +0000

For about a month, every social preview card on a site I build was silently cut off mid-word. Not truncated with an ellipsis — cut inside a word. PDF & image tools, con. The con is converters, sliced in half.

Nobody reported it. Preview cards are the one thing you never see on your own site — they only show up when someone else shares your link on Slack, Discord, or X. So it just sat there, on every page, in every language.

Here's the line that did it:

// OG card subtitle
<text ...>${esc(String(sub).slice(0, 60))}</text>

slice(0, 60). Take the first 60 characters. Simple, obvious, and wrong — because "60 characters" has no idea where words end. If character 60 lands in the middle of converters, you ship conv.

Why it survived so long

Two reasons, and both are worth internalizing:

The output is invisible to the author. OG cards render off-site. My build succeeded, the page looked fine, the card image generated without error. Everything green. The bug only exists in the one context I never look at.
It was in a shared template. One ogSvg() function renders the card for every tool page. So the bug wasn't on one page — it was on 164 tools × the locales each ships. 836 cards, all the same slice, all cut mid-word.

That second point is the real lesson. A bug in a leaf component hurts one page. A bug in the thing that generates every page hurts all of them at once, and it does it quietly.

The naive fix, and why it isn't enough

The obvious fix is "cut at the last space instead of at character 60":

const cut = s.slice(0, n);
return cut.slice(0, cut.lastIndexOf(" ")) + "…";

This works great for English. It falls apart the moment you have more than one language.

Japanese, Chinese, and Korean don't put spaces between words. 無料オンラインツール is one run of characters with no space to find. lastIndexOf(" ") returns -1, slice(0, -1) chops off the last character, and now your CJK subtitle is missing a character and has a floating ellipsis. You traded a visible English bug for a subtle CJK one.

What actually shipped

function clip(s, n) {
  s = String(s == null ? "" : s).trim();
  if (s.length <= n) return s;
  const cut = s.slice(0, n);
  const sp = cut.lastIndexOf(" ");
  // Latin scripts break on the space. CJK has no spaces, so if there's no
  // space — or it's too early to be a real word boundary — just hard-cut.
  return (sp > n * 0.5 ? cut.slice(0, sp) : cut).replace(/[,·、，\s]+$/, "") + "…";
}

The sp > n * 0.5 guard is the whole trick. If the last space sits in a reasonable spot, break there (Latin). If there's no space, or it's suspiciously early — meaning it's probably not a real word boundary — hard-cut the character run (CJK). The trailing replace strips a dangling comma or CJK punctuation so you never get image tools,….

It's not linguistically perfect. It doesn't need to be. It needs to never cut converters into conv and never eat a Japanese character. Those two failures are what people actually see.

The takeaway

If you generate anything from a shared template — OG cards, emails, PDFs, filenames — the failure mode isn't "one broken thing." It's "one broken thing, replicated everywhere, in the one place you never look." Two habits catch it:

Look at the artifact, not the build log. The build passing tells you nothing about whether the card reads correctly.
slice() is not a text-truncation function. It's a character-count function. The moment human-readable text meets a non-space-delimited language, they stop being the same thing.

I hit this building Toolio, a set of small browser tools that ship in 16 languages — which is exactly why the CJK edge case wasn't optional.