Mehdi Akiki

A practical Rust reference

Rust Failure Atlas

Your build fails only in release. A task stops making progress. A library works on one machine but fails on another. Start with the error or the symptom, then follow a check that can narrow the cause.

Find your failure

Paste the first error line or describe what you see. If several causes fit, use the first check to tell them apart.

711

symptom-first records

689

records with a downloadable failing and repaired fixture; 22 link to articles without an executable fixture yet

99

mechanism trails connecting related failures

Start with the problem in front of you

Choose a symptom, make the first check, then follow the explanation or a smaller failing case.

A request stops making progress

Check whether the request is waiting for Rust work, a free connection, or PostgreSQL.

The request timed out. Did its work stop?

Find out whether the database is still working before you retry the request.

Memory grows while a consumer is slow

Follow data through the tasks and queues. Check which of them still holds it.

The build changed, or kept an old result

Compare the exact build inputs, generated files, dependency features, and database descriptions.

A native dependency works only on one machine

Compare the target architecture and the libraries available to the deployed process.

A failure test passed without proving the rule

Check the intended error, stored state, and a valid control before trusting a rejection.

An account boundary disappears in a cache or tool

Trace the authenticated scope through reads, cache hits, invalidation, and the effect boundary.

To follow new engineering articles, subscribe with RSS.

Below the application layer

These 27 cases depend on more than the source file: the final link, a symbol table, a C toolchain, the target triple, the allocator on the other side of an FFI call, a Cargo profile, or the test harness. For 16 of them the fixture goes past a single compiler run: nm and readelf, a link map, a linker under a memory cap, a C host built with AddressSanitizer, paired Cargo profiles, or a subprocess deadline.

What the final artifact actually exports, which symbols survive LTO, and what the linker needs to finish.

Which native library a build script finds, who owns it in the graph, and which machine its objects are built for.

Which side owns an allocation, what a value means on the other side of the boundary, and what a panic may cross.

When Cargo reruns a build script, what a profile changes, and how doctests and packaging see a different crate.

Timers, blocking work, wakeups, shared test processes, and layout decisions that only show up when the program runs.

01

Begin with the symptom

Keep the exact error and note what changed: Rust version, target, profile, or when the failure happens.

02

Separate the possible causes

Choose a check whose result changes what you investigate next. A build failure may come from the Rust code, the linker, or a missing library.

03

Check the repair

Compare the failing example with the repaired one. Check what changed and what the result establishes. The explanation connects that result to the sources.

Inclusion standard

A plausible explanation is not yet a case file

I include a failure when I can state the symptom without pretending it has only one cause, show a minimal or controlled reproduction, identify at least one misleading shortcut, and connect the repair to evidence that would fail again if the mechanism returned.

A fixture run shows two things: the failing project fails with the recorded output, and the repaired project passes. It does not check the written explanation, which is my reading of the mechanism with primary sources cited on each case page. 22 records link to long-form articles instead of case pages. They do not have an executable fixture yet, and search results say so.

  • Exact toolchain, target, profile, and dependency context
  • Small reproduction or controlled interleaving
  • Likely cause separated from confirmed cause
  • A repair with a regression check
  • Primary documentation or upstream implementation source
  • A review date when version-sensitive behavior matters

Reference layer

Compiler diagnostics and library contracts

The other 684 records are the reference layer. Most of them start from a compiler diagnostic or a documented standard library contract, where the cause is closer to the code you wrote: borrow and trait errors, macro and type diagnostics, collection and I/O behavior, numeric edge cases, and edition changes. 322 of them are keyed to a compiler error code. All of them stay in search and on their family pages.

A case belongs in the atlas when copying the final fix without understanding the mechanism is likely to make the failure return in another target, task, dependency, or release. For language concepts without a failure symptom, use the Rust Under the Hood series. For a compiler error code on its own, the official Rust error-code index is usually the faster reference.

Add evidence, not noise

Have a Rust failure that disappears when simplified?

Send the smallest evidence you still trust: the symptom, versions, target, profile, and what makes it appear or disappear. A useful report can become an Atlas case without exposing private source code.

Share a reproducible symptom