Recovery guide
When Nox
Common Nox failures, what they mean, and the smallest useful next check.
Inspect state before changing files.
nox status
nox validate
nox targets
nox graphStatus shows the configured root, build directory, configuration, tools, flags, and target count. Validation and graph commands isolate project-file and dependency problems without compiling.
Build is not configuredRun `nox setup build` before `nox build`. Source edits do not require setup, but build-directory, toolchain, and configuration changes do.
Rider not foundInstall the required tool and make sure it is visible through PATH. Native detection checks cc, clang, gcc, c++, clang++, g++, ar, and llvm-ar in that order.
Header changes do not rebuildInspect the target .d file under build/<configuration>/<target>. Nox delegates dependency discovery to the compiler with -MMD and -MF.
Unknown targetRun nox targets to see declaration order and nox graph to see dependency order. Dependencies must name targets in the same project.
Dependency cycleThe graph must be acyclic. A target that depends on another target which eventually depends back on it cannot be ordered.
Run cannot find an executableBuild an executable target and pass its exact target name. Libraries are not runnable project targets.
Rust behavior is unexpectedNox's Rust backend invokes rustc directly and uses the first source. Cargo dependency resolution and Rust incremental compilation are not modeled by this backend.
Install cannot write /usr/localUse a user-owned prefix such as nox install --prefix "$HOME/.local", or use appropriate permissions for the system prefix.
Reconfigure without deleting installs.
nox setup --reconfigure removes the selected build directory and writes fresh state. nox rebuild configures and builds from scratch. nox clean removes generated build state but intentionally leaves installed artifacts alone.