Troubleshooting

`hop: command not found`

Open a new terminal after installation. Confirm the install directory is on PATH:

command -v hop
printf '%s\n' "$PATH"

The default Unix location is ~/.local/bin. On Windows it is %LOCALAPPDATA%\Programs\Hop.

An agent integration does not activate Hop

hop skill install --force

The command refreshes both default skill bundles. Restart the agent client. For Codex Desktop, mention $hop in a task as a deterministic activation fallback. For another compatible runtime, confirm that it reads ~/.agents/skills or run hop skill install --path /path/to/agent/skills --force.

The installer cannot find a release

Only published Gitea Releases appear through the public releases API. Drafts and an instance that is not live will return an error; published prereleases are supported. Pin an existing tag with HOP_VERSION, or use the source build until the first release is published.

Git is too old

Hop requires Git 2.40 or newer for structured, explicit-base merge-tree behavior:

git --version

Upgrade Git through the operating system package manager before retrying.

Exit code 20: merge conflict

The agent should adopt the returned reconciliation prompt and workspace, resolve both intents, run hop check, propose, and land again. Users should not need to perform ordinary source merges.

Exit code 22: validation failed

The accepted head did not advance. Inspect the recorded output, fix the attempt workspace, and rerun the check.

Exit code 23 or `Root: diverged`

Hop found visible files or index state it will not overwrite. Preserve those changes. Capture them as a new Hop task or resolve them intentionally, then retry hop land. Do not bypass this with hop accept in interactive workflows.

Internal ref or object warning

hop doctor

If SQLite is healthy and the report specifically identifies derived refs:

hop doctor --repair

Do not repair while a final validation command is running.

Automatic push failed

The accepted state remains safe locally. Hop never force-pushes. Retry a transient network or authentication failure with:

hop push

If the remote branch moved independently, preserve both histories and resolve the divergence intentionally; do not replace this with a force-push.

A secret was pasted

Rotate it. Hop redaction reduces durable exposure but cannot prove that every credential format, attachment, agent log, or external system omitted the value.