Troubleshooting
Symptom, cause and next step for the usual failures of the harness and the CLI.
Customization is still pending
rei init deploys the skeleton with REI:PENDIENTE markers in the project documentation. While markers remain, rei init status reports the pending documents and exits with 1: the agents would work with generic rules.
- Run
rei init statusto see which documents are missing. - Open
/personalizein OpenCode or Claude Code, or ask «personaliza mi proyecto» so the Initializer runs the interview. - Check that
AGENTS.mdand.rei/docs/project/describe your repository and not the skeleton. - Repeat
rei init status: it must exit 0 when nothing is pending.
rei check fails
rei check runs its harness checks and the checks declared in .rei/config.json. It exits with 1 if there is at least one [FAIL] or if a project check fails; code 2 is reserved for incorrect usage.
- Read the output: tell a harness failure apart from a project check.
- If a check fails, run its command separately and fix the cause.
- Check that the check is declared correctly:
id,descriptionandcommandas an array. - Repeat
rei check --quietuntil you get 0. Do not disable the check to make it pass.
More than one Work Item in in_progress
The harness only allows one active Work Item. rei status set <id> in_progress rejects a second Work Item, also with --force; rei check, rei doctor and rei items status fail if they detect more than one.
- Run
rei items statusand find the Work Item marked with << ACTIVO. - Close the active one (review or done), block it or finish its review.
- Confirm that none is left in in_progress.
- Start the next Work Item only when the previous one has left the state.
Invalid links.json
.rei/specs/<id>/links.json is a recoverable local index, not the source of truth. If the JSON is broken or its shape is invalid, rei validate reports it as a WARN —never as a FAIL— and rei item show or rei items status flag it as a note without blocking the Work Item.
- Run
rei validateto read the specific cause. - Find the issue by its marker rei:work-item:<id>, not by the title or the label.
- Rewrite
links.jsonin its valid shape: provider, repo, issue, url, base and epic where they apply. - Validate again; the warning disappears without changing the Work Item's state.
The session does not start
rei session start <id> <tipo> only creates the session if the Work Item exists, the type matches meta.json and its state is pending. In any other case it rejects with the cause and next step without writing current.md.
- Run
rei item show <id>to see the real type and state. - If the type does not match the argument, repeat the command with the type from
meta.json. - If the state is ready, do not restart: approve the planning or ask for changes.
- If it is in in_progress, review or changes_requested, resume the existing session with
rei item show <id>. - If it is in done or blocked, create a new Work Item with
rei new.
gh missing or not authenticated
The GitHub Issues integration relies on gh for the real actions; the rei CLI never calls GitHub. If gh is not installed or has no session, the message says so with the cause and next step. These are warnings that do not block rei github: the command exits 0.
- Install GitHub CLI and check that
ghis on the PATH. - Run
gh auth loginand thengh auth status. - Run
rei github statusto see the offline state of the configuration and the availability ofgh. - Repeat the GitHub Issues action only when
ghresponds with a valid session.
The viewer does not open or its local address does not respond
rei view serves the viewer locally. With no mode it stays in the foreground until Ctrl+C; --open starts or reuses the server in the background and opens the browser without blocking. If the page does not respond, the background server may have stopped or lost its temporary record.
- Run
rei view <id> --opento start or reuse the server and open the browser. - If it still does not respond, stop the server with
rei view --stopand open it again. - Without
<id>, the viewer uses the Work Item of the active session; check that it exists withrei session. - Check
viewer.autoOpenOnReadyif you expected it to open at the approval gate.
Invalid checksum when updating
rei update downloads the latest release, verifies the archive's SHA-256 against checksums.txt and only then replaces the binary. An invalid checksum, a network failure or a permission error abort the update with code 1 and leave the binary undamaged.
- Run
rei update --checkto confirm the available version without downloading. - Repeat
rei updatewhen the network is stable. - If the integrity failure persists, download the archive from the releases page and verify its SHA-256 against
checksums.txtbefore replacing the binary.
The project does not use git
git is not mandatory: the workflow keeps working in read mode. What is lost is the diff-bounded review and the commit record in meta.json. rei check initializes git automatically if it is missing.
- Run
rei check: it creates the structure and initializesgitif it does not exist. - If you decide to use
git, confirm the repository has an initial commit before approving a Work Item. - Without
git,base_commitandlast_review_commitstay empty; the flow is not blocked by it. - With
git, record the commits before requesting a review so thatrei review-diffbounds the diff.
The symptom is not here
This page covers the failures documented by the usage guide and the harness documents. If the symptom does not appear, start with the matching frequently asked question and, if it is not there either, look up the specific command with rei <comando> --help.
A human sign-off releases the sheet. Silence is not approval.