Troubleshooting

This guide groups common symptoms by the layer most likely to own the failure.

It does not replace exact diagnostics in Diagnostics.

Command Not Found

Symptom:

./bin/zero: not found

Check:

ls bin/zero
make

If release artifacts are missing and you intentionally want to rebuild from the

seed:

make bootstrap-from-seed

Needs verification: whether a distributed artifact bundle was expected for your

checkout.

Compiler Not Found In The LSP

Symptom:

0x0 compiler not found

Fix:

make bootstrap-from-seed

Or point the LSP at an existing compiler:

ZERO_LSP_COMPILER="$PWD/bin/zero" tools/zero-lsp --check examples/add.0x0

See Editor Support.

Parse Or Shape Errors

Typical causes:

• unbalanced parentheses;
• unterminated strings;
• unsupported top-level forms;
• malformed function, import, export, ADT, or match forms.

Start with:

tools/zero-lsp --check path/to/file.0x0

Then compare with the grammar in Syntax and

Language Guide.

Type Or Arity Errors

Example failure:

./bin/zero run examples/compiler2-import-type.0x0

Expected result: non-zero exit status with an argument type mismatch diagnostic.

Check:

• function annotation arity;
• call argument count;
• concrete argument types such as I64, Text, Bool, and Unit;
• parametric type-constructor arity.

See Diagnostics and Type And Effect System.

Import Errors

Check:

• relative imports are resolved from the importing file's directory;
• package imports use pkg:name and require a matching dep name path row in

0x0.lock;

• namespaced imports expose alias.name;
• imported modules with ↦ export only the listed functions.

Reference docs:

• Language Guide
• Packages
• Package System

Pure Function Calls Host Effects

Symptom: a pure function calls read-file, write-file, print, panic, or

another effectful function.

Fix:

• remove (cap pure) if the function is intentionally effectful;
• move the host effect behind an explicit runtime boundary;
• keep pure helpers separate from file, process, network, crypto, or hardware

operations.

Reference docs:

• Capabilities
• Runtime Production Capabilities

Backend Unsupported

The compiler has multiple backend surfaces and not every source slice is

supported by every backend. If a path fails with a backend unsupported

diagnostic, check:

• Backend Coverage
• Compiler Guide
• Object Format
• Linker

Use a smaller example to isolate whether the failure belongs to source

semantics, lowering, object generation, linking, or runtime execution.

Documentation Check Fails

Run the bounded checks first:

make documentation-impact-check
make public-site-link-check
make public-site-build-check

Then run:

make docs-check

Common causes:

• a behavior change without updated docs;
• a dead relative link;
• generated API docs not refreshed after public doc annotation changes;
• a beginner page claiming unimplemented behavior.

Reference docs:

• Documentation Standard
• Documentation Impact Review

Self-Host Drift

Symptom:

stage2.oisa != stage3.oisa

Treat this as a compiler fixed-point failure. Check for nondeterministic output,

changed source ordering, annotations leaking into emitted OISA, or parser

differences between paths.

Reference docs:

• Bootstrap Model
• Maintainer Manual

Static Site Looks Stale

Check the source docs first, then rebuild or redeploy the site bundle according

to Public Site Build and

Public Site Release Checklist.

If a hook reports redeployment, verify the commit hash it names.