Troubleshooting
The command is not found
Section titled “The command is not found”Confirm the extracted rad binary is executable and its directory is on PATH. Run the absolute path once, then rad --version.
No supported project is detected
Section titled “No supported project is detected”Run rad doctor --json. Confirm that the required lockfile, project manifest, and test runner exist in the workspace Radforge should analyze. For Go, confirm that go.mod or go.work is at the selected root and that go test -count=1 ./... passes in each module. Use --language go, --language typescript, or --language python when the repository contains more than one language.
Changed analysis selects nothing
Section titled “Changed analysis selects nothing”rad changed selects Go, TypeScript/JavaScript, or Python production paths. Split mixed-language changes because one run handles one language.
Verify the comparison ref exists locally and includes the expected diff. Try git diff --name-only <ref>...HEAD. Review repeated --exclude flags and .muttignore.
Authentication fails
Section titled “Authentication fails”Confirm RADFORGE_API_TOKEN is set in the same process environment and has no surrounding whitespace. Do not print the value. Check RADFORGE_REMOTE_URL, then run rad remote doctor.
A remote plan is rejected
Section titled “A remote plan is rejected”Regenerate the plan with the current CLI. Confirm that every source file is tracked by Git with git ls-files --error-unmatch <path>. Run rad remote doctor to see the languages and upload limits supported by the server.
A run is stuck or fails
Section titled “A run is stuck or fails”Capture rad --version, rad doctor --json, rad remote doctor --json, and rad remote status --run <id> --json. Remove secrets and private paths that support does not need. Include the run ID. Do not attach source archives unless support provides a secure upload method and asks for specific files.