Naturalists used to walk into the world with a notebook, a pencil, and the conviction that everything they encountered deserved to be drawn. The drawings are what survive. The pinned moth, the careful caption beneath, the date and the place and the name of the person who saw it first. You can read a hundred bird books that do not contain a single drawing and forget every one of them. You will remember the Audubon plate of the wood thrush for the rest of your life.

Software has produced as many strange specimens as nineteenth-century natural history, and we treat them worse. A famous bug is usually a Stack Overflow link, a Wikipedia paragraph, a stack trace on a slide deck. The form is forgettable on purpose. I have been thinking for a while that there should be a field guide for the famous ones, in the actual sense: pinned and labeled, with a hand-drawn diagram and a paragraph in a careful voice, and with the date and the place and the person who saw it first.

So I made one. bugs.ma-r-s.com is a catalog of software bugs from the published record, beginning in 1947. Each has a specimen ID, a pseudo-Latin scientific name, a taxonomic family, a date, a habitat, an observer, a one-line tagline, and a custom inline-SVG diagram drawn for it. The body is a five-to-eight-hundred word writeup in the register I have been developing in this blog over the past month. The catalog grows when a new specimen earns its page.

The catalog

Curated rather than encyclopedic. The criteria, loosely held: the bug had to be real and well-documented; the cause had to be specific and explicable in a paragraph; the consequences had to be either instructive, funny, or both. The reading order is curatorial, not chronological, the way a gallery is hung rather than a calendar.

Some of the entries are famous for being absurd. The 500-mile email is the canonical case of an impossible-sounding bug report that turned out to be physics: a sendmail timeout of zero defaulted to about three milliseconds, the campus network was fully switched, and the round-trip-time horizon for a successful SMTP handshake worked out to roughly five hundred miles. The Wi-Fi that worked only when it rained is more recent, but in the same family: a tree just tall enough to clip the Fresnel zone of a wireless link, branches that bent under the weight of rainwater, packets that flowed only while the canopy was loaded. OpenOffice would not print on Tuesdays because PostScript files began with %%CreationDate: (Tue ...) and Linux's file utility had a magic-byte rule for Erlang bytecode that started with the same three letters.

Some are famous for the body count. Therac-25 killed at least three patients between 1985 and 1987 when a race condition between operator keystrokes and turntable rotation fired the high-energy electron beam through nothing instead of through the X-ray target. The Patriot missile failed to intercept a Scud at Dhahran in 1991, killing twenty-eight American soldiers, because its system clock drifted 0.34 seconds across a hundred hours of uptime, multiplied by a missile travelling at 1,676 meters per second.

Some are famous for the consequences. Knight Capital lost $440 million in 45 minutes on August 1st, 2012, because a deprecated flag bit was reused for a new feature on the same morning a deployment missed one server out of eight. The Pentium FDIV bug omitted five entries from a 2,048-entry SRT lookup table and produced wrong floating-point divisions for about one input pair in nine billion, which Intel handled badly enough that the recall cost $475 million and the modern era of public-bug-disclosure doctrine begins there.

And one is famous for not having happened. Nuclear Gandhi, the integer-underflow myth from Civilization (1991), is included precisely because the bug almost certainly never existed but became canonical anyway when Civilization V (2010) implemented an intentionally-aggressive Gandhi as an inside joke about the legend. It is the only entry that needed a different kind of careful labeling: the specimen is the story, not the bug.

The diagrams

The aesthetic is naturalist field guide. Aged paper, sepia ink, deep botanical green for the foliage references, cinnabar red as the accent for the moment-of-failure highlight. A four-family typographic stack: Cormorant Garamond for display, EB Garamond for body, JetBrains Mono for the specimen IDs and code references, and Caveat for the handwritten annotations on each diagram. Every diagram is drawn from scratch as inline SVG. Nothing generated, nothing borrowed. A small set of CSS classes (ink, accent, leaf, hand) keeps the visual language consistent across the catalog without making any two entries look the same.

Across the background of the catalog index, small code-glyph creatures drift slowly across the page. They are not decorative in the abstract sense. They are the metaphor made literal: bugs that look like code, walking across the field where the real specimens are pinned.

The diagrams take license. The Patriot-Missile entry shows a clock face with two hands offset by 0.34 seconds beside a trajectory diagram with the predicted impact point drawn 570 meters short. The Pac-Man entry shows the left half of the maze drawn correctly and the right half rendered as the random memory the drawing routine read after the level counter overflowed. The Hopper-Moth entry is a logbook page with the moth drawn flat under two strips of tape and the words "first actual case of bug being found" in handwriting above it. None of these are technically necessary. They are necessary in the sense that an Audubon plate of a wood thrush is necessary: you remember a thing you have seen drawn.

Why I built it

There are good books about specific bugs (Nancy Leveson's investigation of Therac-25 is a monograph) and there are good aggregator pages (500mile.email collects absurd cases by category). What does not exist, as far as I have found, is a small, designed object that treats the famous bugs as cultural artifacts worth presenting carefully. Software history has a hagiography (Hopper, Turing, von Neumann), a tragedy genre (Therac, Knight), and a folklore tradition (the 500-mile email, the Tuesday printer). What it does not have yet is its own Audubon, and I do not think I am the person to write that one. But I can write careful pages, one specimen at a time, and so I have started.

The catalog grows when a specimen earns its page. There are easily another twenty I would like to add: a 1990 AT&T long-distance outage, a 2017 S3 typo, a 2019 Cloudflare regex, entries that are really about etymology (why "patch," why "Easter egg," why "kludge"), the schoolboy-and-the-AIM-9 story, the iKettle, the leap-second cascade. They will arrive when each is ready, not on a schedule.

Live at bugs.ma-r-s.com. Source on GitHub.