Operations · Troubleshooting

Troubleshooting

Symptom, cause and next step for the usual failures of the harness and the CLI.

ten symptoms · cause · next step

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.

  1. Run rei init status to see which documents are missing.
  2. Open /personalize in OpenCode or Claude Code, or ask «personaliza mi proyecto» so the Initializer runs the interview.
  3. Check that AGENTS.md and .rei/docs/project/ describe your repository and not the skeleton.
  4. 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.

  1. Read the output: tell a harness failure apart from a project check.
  2. If a check fails, run its command separately and fix the cause.
  3. Check that the check is declared correctly: id, description and command as an array.
  4. Repeat rei check --quiet until 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.

  1. Run rei items status and find the Work Item marked with << ACTIVO.
  2. Close the active one (review or done), block it or finish its review.
  3. Confirm that none is left in in_progress.
  4. Start the next Work Item only when the previous one has left the 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.

  1. Run rei item show <id> to see the real type and state.
  2. If the type does not match the argument, repeat the command with the type from meta.json.
  3. If the state is ready, do not restart: approve the planning or ask for changes.
  4. If it is in in_progress, review or changes_requested, resume the existing session with rei item show <id>.
  5. 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.

  1. Install GitHub CLI and check that gh is on the PATH.
  2. Run gh auth login and then gh auth status.
  3. Run rei github status to see the offline state of the configuration and the availability of gh.
  4. Repeat the GitHub Issues action only when gh responds 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.

  1. Run rei view <id> --open to start or reuse the server and open the browser.
  2. If it still does not respond, stop the server with rei view --stop and open it again.
  3. Without <id>, the viewer uses the Work Item of the active session; check that it exists with rei session.
  4. Check viewer.autoOpenOnReady if 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.

  1. Run rei update --check to confirm the available version without downloading.
  2. Repeat rei update when the network is stable.
  3. If the integrity failure persists, download the archive from the releases page and verify its SHA-256 against checksums.txt before 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.

  1. Run rei check: it creates the structure and initializes git if it does not exist.
  2. If you decide to use git, confirm the repository has an initial commit before approving a Work Item.
  3. Without git, base_commit and last_review_commit stay empty; the flow is not blocked by it.
  4. With git, record the commits before requesting a review so that rei review-diff bounds 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.

Planning approval

Pending

A human sign-off releases the sheet. Silence is not approval.

Approval is recorded from the CLI; the viewer does not replace it.