Skip to content

Annotate an impossible 'X is not defined' with why module resolution missed - #550

Draft
Jarred-Sumner wants to merge 3 commits into
mainfrom
claude/diag-impossible-referror
Draft

Jarred-Sumner wants to merge 3 commits into
mainfrom
claude/diag-impossible-referror

Conversation

@Jarred-Sumner

@Jarred-Sumner Jarred-Sumner commented Sep 2, 2026 •

Copy link
Copy Markdown
Collaborator

Field telemetry from --compile --bytecode --splitting apps occasionally shows ReferenceError: X is not defined for a name the throwing module imports (or declares), sometimes after the same binding resolved for over an hour in the same process. For an import used inside a module function the engine can only produce that error if AbstractModuleRecord::resolveImport misses both when the CodeBlock is linked and on every dynamic re-resolve afterwards, and by construction (pointer-identical atoms, immutable import/export tables) it should not. We have not been able to reproduce it, so this makes the next field occurrence self-describing.

When get_from_scope (LLInt, Baseline, and DFG's GetDynamicVar) is about to throw for a name and a JSModuleEnvironment on the function's scope chain imports or declares a binding with the same text, the message gets a suffix such as

foo is not defined [bun-diag rt=10 jt=2 atom=1 intable=1 rc=1 heq=1 len=3 env0:imp=1,hdr=1,ptrimp=1,hashimp=0,txtimp=0,sym=0,txtsym=0]

which distinguishes: the record resolves the name now but the op was linked unresolved (imp=0 with rt unresolved); the import entry is present by linear scan but the hash lookup misses it (ptrimp=1,hashimp=0 — damaged bucket array / map header hdr=0 / key hash word heq=0); an entry with equal text but a different StringImpl (txtimp=1 — two atoms, plus whether the identifier is the atom the table holds for its text, intable); the exporter's export table in the same terms (xptr/xhash/xtxt/xenv); and the module environment's own symbol table (sym/txtsym) for module-level vars.

Only the throw path is touched, and only when a module environment is on the chain and one of the checks fires, so ordinary undefined-global errors (including inside modules) are byte-for-byte unchanged — verified with plain and --compile --bytecode --splitting builds. Every field is a small enum so telemetry that only keeps a hash of the message can still brute-force it. Exercised end to end with a temporary fault injection that makes tryGetImportEntry miss one name (not included).


Second commit: the same for TDZ. op_check_tdz names the binding by its source text; if that text is an import or module-scope binding of a module environment on the function's scope chain, the slot it resolves to is inspected now and the message is annotated only when it is non-empty (the read that fed the check was wrong) or empty although its module finished evaluating without error (the environment was damaged):

Cannot access 'fnA' before initialization. [bun-diag tdz jt=2 env1:imp res=0 slot=0 xst=6 tst=6 self=0]

Ordinary TDZ (a lexical binding read before its declaration ran, an import of a module still evaluating in a cycle) is unchanged — verified with a cyclic-import case. Motivated by field rows where an import of a plain hoisted function threw TDZ hours into a process.

…missed

When get_from_scope is about to throw ReferenceError for a name and a
JSModuleEnvironment on the function's scope chain imports or declares a
binding with the same text, the error should not have been possible.
In that case append a short, fixed-vocabulary suffix to the message that
says which invariant is broken: whether the record resolves the name
now, whether the import entry is present by pointer but missed by the
hash lookup (damaged table or hash word), whether an entry with equal
text but a different StringImpl exists (two atoms), whether the
identifier is the atom the table holds for its text, and the same for
the exporter's export entries and the environment's symbol table.

Only the throw path is touched and only when a module environment is on
the chain and one of those checks fires, so ordinary undefined-global
errors are unchanged. Every field is a small enum so telemetry that
only keeps a hash of the message can still recover it.
@github-actions

github-actions Bot commented Sep 2, 2026

Copy link
Copy Markdown

Preview Builds

Commit Release Date
ad86a94b autobuild-preview-pr-550-ad86a94b 2026-09-02 14:15:07 UTC

op_check_tdz names the binding by its source text. If that text is an
import or module-scope binding of a module environment on the function's
scope chain, look at the slot it resolves to now: a non-empty slot means
the read that fed the check produced a wrong value, and an empty slot in
a module that finished evaluating without error means the environment
was damaged. Ordinary TDZ (a lexical binding read before its declaration
ran, a binding of a module still evaluating in a cycle) is unchanged.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant