Troubleshooting

L0 Troubleshooting Guide

I use this as my deterministic troubleshooting reference.

Quick Triage

1. Run ./bin/l0c verify <file.l0>.
2. If verify fails, classify by error class in docs/ERROR_MODEL.md.
3. If verify passes but runtime surprises happen, inspect imgmeta, mapcat, tracecat, and tracejoin.

Common Failure: Non-Canonical Source

Symptom:

• error: invalid module shape or non-canonical input

Checks:

• section order is exact
• function ids contiguous (f0..)
• block ids contiguous (b0..)
• one terminator per block
• value lines include : tN

Fix path:

• compare with docs/HOW_TO_WRITE_L0.md
• minimize failing file and re-verify

Common Failure: Def-Before-Use

Symptom:

• verifier returns parse/non-canonical class on otherwise structured file

Checks:

• every vN used by ret/cbr/call/binary/memory/intrinsic was defined earlier in function

Fix path:

• move definitions before use
• keep SSA single definition per vN

Common Failure: Pointer Type Misuse

Symptoms:

• verifier failure on ld/st/gep/alloca/malloc/free/write

Checks:

• pointer operands use p0<i8> paths in current bootstrap contract
• non-pointer operands where required (malloc size, write len, exit code)

Fix path:

• align with typing rules in docs/GRAMMAR_AND_TYPING.md

Common Failure: Corrupt Image

Symptom:

• error: invalid or corrupt L0IMG

Checks:

• run ./bin/l0c imgcheck <img> first
• rebuild image from source with build

Fix path:

• avoid editing binary payloads manually
• regenerate debug-map/schema side artifacts with build --debug-map --trace-schema

Common Failure: Run Argument Rejection

Symptom:

• error: invalid run argument (expected unsigned decimal)

Fix path:

• pass decimal unsigned integer args only
• avoid signs, hex, or non-numeric tokens

Debugging Runtime Behavior

Use this sequence:

./bin/l0c build <file.l0> /tmp/x.img --debug-map /tmp/x.map --trace-schema /tmp/x.schema
./bin/l0c run /tmp/x.img <args...> >/tmp/x.out 2>/tmp/x.trace
./bin/l0c imgmeta /tmp/x.img
./bin/l0c mapcat /tmp/x.map
./bin/l0c tracecat /tmp/x.trace
./bin/l0c tracejoin /tmp/x.trace /tmp/x.map

Interpretation:

• imgmeta tells me kernel selection and code size
• mapcat tells me instruction id ranges
• tracecat gives raw trace values
• tracejoin maps trace ids to code ranges