A request stops making progress
Check whether the request is waiting for Rust work, a free connection, or PostgreSQL.
Is Your Rust Request Waiting for a Connection or for PostgreSQL? →Follow the related checks →Rust, explained from the problem you can see
A Rust program can compile and still get stuck, use too much memory, or leave a database write uncertain. Start with what you can observe. Follow the explanation, check the example, and see what a useful fix changes.
I am Mehdi Akiki. These guides connect Rust code to the database, runtime, compiler, and operating system it depends on. Each investigation starts with a concrete problem and explains the terms as they become useful.
You do not need to read the whole atlas. Choose the question closest to yours.
Check whether the request is waiting for Rust work, a free connection, or PostgreSQL.
Is Your Rust Request Waiting for a Connection or for PostgreSQL? →Follow the related checks →Find out whether the database is still working before you retry the request.
A Rust Timeout Can Leave PostgreSQL Work Running →Follow the related checks →Follow data through the tasks and queues. Check which of them still holds it.
A Bounded Rust Channel Does Not Bound Its Database Producers →Follow the related checks →You can also inspect my changes to the Rust compiler and the design of Bitarena, a Rust collection that keeps stable handles while values are added and removed.
147
long-form articles
Each article sits in one map, listed in the article directory below.
694
failure case pages
Symptom-first cases in the Rust Failure Atlas, grouped by failure family.
694
cases with a failing and a repaired fixture
A fixture run shows that the failure reproduces and the repair passes. It does not check the explanation, and performance claims stay conditional.
A failure rarely respects one documentation category. An async Send error can begin in a type, become stored future state, meet a runtime requirement, and surface as a trait diagnostic. The atlas keeps these paths visible.
Failures
Symptom-first investigations for failures that depend on timing, target, profile, version, feature graph, linker, or unsafe invariants.
716 entries available in this map
The cases above are from the part of the Failure Atlas that sits below the application layer. Every failure case is listed in the Atlas linked above; related articles are in the article directory below.
Compiler
Source-to-binary maps through parsing, expansion, resolution, HIR, THIR, MIR, trait solving, borrow checking, code generation, diagnostics, and rust-analyzer.
18 entries available in this map
14 more entries are available in the complete article directory below.
Build
Feature resolution, MSRV, build scripts, fingerprints, incremental compilation, proc-macro builds, native dependencies, code generation, and linkers.
17 entries available in this map
13 more entries are available in the complete article directory below.
Async
Future layout, Send boundaries, cancellation, wakeups, scheduling, cooperative budgets, atomics, backpressure, task ownership, and shutdown.
34 entries available in this map
30 more entries are available in the complete article directory below.
Memory
Layout, variance, drop checking, pinning, provenance, aliasing, initialization, destruction, trait objects, and the proof obligations behind safe APIs.
45 entries available in this map
41 more entries are available in the complete article directory below.
Targets
ABI contracts, native libraries, WebAssembly, musl, operating systems, architectures, embedded targets, cross-compilation, and host capabilities.
9 entries available in this map
5 more entries are available in the complete article directory below.
Releases
Important stable changes translated into affected code, compatibility boundaries, migration checks, and behavior compared across toolchain versions.
2 entries available in this map
Complete article directory
Long-form Rust articles, grouped by map. The symptom-first failure cases have their own directory in the Rust Failure Atlas.
Claim ledger
I separate deterministic claims from source-level constraints and machine-dependent performance hypotheses. Each record names the observation that would prove my explanation incomplete. This prevents an attractive benchmark number from becoming a universal Rust rule.
RCL-001 · Executable check
Changing reader chunk size must not change the ordered match IDs or absolute offsets.
Falsifier: Any read limit produces a different match tuple from one-shot search.
Evidence: chunk_partition_does_not_change_matches
Read the article →RCL-002 · API or method bound
Compact recognition state does not remove bytes needed by a streaming output contract.
Falsifier: A replacement or delayed-match API can release unresolved bytes and still reproduce one-shot output for every split.
Evidence: Longest-match buffer bound plus split-point replacement oracle.
Read the article →RCL-003 · Executable check
Standard, leftmost-first, and leftmost-longest select different valid results for one fixed input.
Falsifier: The pinned crate returns an identical tuple for all three configured match kinds.
Evidence: match_kinds_choose_different_documented_results
Read the article →RCL-004 · Executable check
Automaton representation is a real observable build choice, not a synonym for Aho-Corasick.
Falsifier: Requesting a DFA does not produce a matcher reporting DFA kind.
Evidence: requested_dfa_kind_is_observable
Read the article →RCL-005 · Measurement required
Linear input complexity does not imply constant per-byte time as the pattern corpus grows.
Falsifier: Nested pattern sets show invariant build cost, memory, selected strategy, and scan distributions across the declared workload matrix.
Evidence: Nested corpus benchmark with kind, memory, output count, and cache-sensitive inputs.
Read the article →RCL-006 · Measurement required
Prefilter value changes with candidate density while logical output remains unchanged.
Falsifier: Enabled and disabled variants have indistinguishable distributions across both rare- and frequent-candidate corpora, or emit different outputs.
Evidence: prefilter_toggle_preserves_logical_output plus paired corpus benchmark.
Read the article →RCL-007 · Measurement required
Pattern shape and haystack byte distribution predict more than pattern count alone.
Falsifier: Controlled corpora with equal counts but different rare bytes, prefixes, lengths, and alphabets show no material strategy or performance change.
Evidence: Five-corpus pattern-shape matrix with corpus hashes.
Read the article →RCL-008 · Measurement required
A loop-carried transition-state dependency can limit a small DFA loop.
Falsifier: Assembly and counters show no loop-carried address dependency or show another cost dominating the declared hot loop.
Evidence: Assembly inspection, cache-sized corpus variants, and hardware counters.
Read the article →RCL-009 · API or method bound
A scanner comparison is valid only after output equivalence and workload symmetry are established.
Falsifier: Two variants with different matches or timed setup still answer the same stated benchmark question.
Evidence: Ordered match oracle, shared corpus hashes, and declared timed regions.
Read the article →RCL-010 · Executable check
A small prefix family can create more overlapping outputs than input bytes.
Falsifier: Searching four `a` bytes for `a`, `aa`, and `aaa` does not return nine overlapping matches.
Evidence: overlapping_prefix_family_has_nine_outputs
Read the article →RCL-011 · Executable check
An arbitrary byte pattern can match inside a valid UTF-8 scalar and yield a range unusable for string slicing.
Falsifier: The continuation-byte match begins at a valid `str` character boundary.
Evidence: arbitrary_byte_match_can_split_utf8_scalar
Read the article →RCL-012 · API or method bound
Slices, buffered reads, and memory maps expose bytes through different ownership and materialization boundaries.
Falsifier: Tracing the declared boundary shows identical ownership, allocation, and source-lifetime behavior for all three inputs.
Evidence: Boundary trace plus cold and warm end-to-end I/O measurements.
Read the article →RCL-013 · Executable check
One compiled matcher can be shared while independent searches keep local iterator state.
Falsifier: Scoped threads cannot borrow the matcher concurrently or their independent match counts interfere.
Evidence: compiled_matcher_is_shared_while_search_state_stays_local
Read the article →RCL-014 · Executable check
An oracle-and-partitions test can make chunk-boundary invariance executable.
Falsifier: A generated partition cannot be compared through the same ordered result representation.
Evidence: chunk_partition_does_not_change_matches
Read the article →Evidence
Failure case pages ship fixtures pinned to a toolchain, and the claim ledger above ties each executable claim to a named test. Depending on the case, the evidence is compiler or runtime output, a symbol table, an object header, a link map, or an AddressSanitizer report. A fixture shows that the failure reproduces and that the repair passes. Whether the explanation is right is still an argument, and each case page cites the primary sources it rests on.
01
Observe
02
Separate
03
Reproduce
04
Prevent
Every case page in the Failure Atlas records the same fields, so two cases can be compared directly.
Source-level experience
I still write and review code directly, including my Rust, Deno, and rust-analyzer open source contributions. The purpose of this atlas is to turn that practice into explanations another engineer can inspect and use.