Hop
7139b9e1a7
Hop-State: A_06FN6FF8HFSFD9ANGK6BY4G Hop-Proposal: R_06FN6FDTK9G17RXFFT82ZYR Hop-Task: T_06FN6CFVXVVAP1KZAJ2X62R Hop-Attempt: AT_06FN6CFVXTRZ8ZDG28QR5Z0
92 lines
2.5 KiB
Markdown
92 lines
2.5 KiB
Markdown
# Troubleshooting
|
|
|
|
## `hop: command not found`
|
|
|
|
Open a new terminal after installation. Confirm the install directory is on
|
|
PATH:
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
hop doctor
|
|
```
|
|
|
|
If SQLite is healthy and the report specifically identifies derived refs:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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.
|