Troubleshooting

Start with hookci doctor. It checks systemd, cgroups, the hookci-run user, network, and whether the hub is reachable.

$ sudo hookci doctor
ok  systemd
ok  cgroup v2
ok  user hookci-run
fail hub unreachable: https://ci.webuno.io

build-box recording
$ sudo hookci doctor
ok  systemd
ok  cgroup v2
ok  user hookci-run
fail hub unreachable: https://ci.webuno.io

Illustration. Run doctor first and read the first failing line.

The output above is illustrative. Real wording can differ.

Agent shows offline

Cause. The service is stopped, crashed, or cannot reach the hub.

Fix. Replace NAME with your agent name.

systemctl status hookci-agent@<installation-id>
journalctl -u hookci-agent@<installation-id> -f
sudo systemctl restart hookci-agent@<installation-id>

The unit uses Restart=always, so a repeated restart usually points to a persistent error in the log.

Hub unreachable

Cause. Outbound connections to the hub are blocked.

Fix. Allow outbound HTTPS (port 443) to ci.webuno.io, or to your own hub if you self-host. Check that a proxy or DNS issue is not interfering. Run hookci doctor again.

Pair token expired or already used

Cause. Pair tokens are single use and valid for 15 minutes.

Fix. Create a new token in Slack App Home with Add agent, or on the hub page after installing the GitHub App, then run:

sudo hookci connect hc_pair_EXAMPLE

If the host was already paired, add --force. See Pair an agent.

Agent exited with code 3 and does not restart

Cause. Either the agent was revoked in Slack App Home, or no checks were found. The unit has RestartPreventExitStatus=3 4, so systemd leaves it stopped.

Fix. If you revoked it by mistake, pair again with a fresh token. If not, run hookci detect in the repo and add a .hookci.yml, for example with hookci init.

No checks found

Cause. Nothing was detected and there is no .hookci.yml at the repo root.

Fix.

hookci detect
hookci init
hookci validate

Detection covers node, python, go, rust, and docker-compose.

Isolation not available (systemd or cgroup v2 missing)

Cause. The host has no systemd or cgroup v2, so jobs cannot be sandboxed.

Fix. Use a distribution with systemd and cgroup v2. As a last resort on repositories you fully trust, run with --isolation none.

A job fails to download dependencies

Cause. The egress proxy allows only listed hostnames on port 443.

Fix. Add the host to egress:

checks:
  egress: [registry.npmjs.org, github.com]

See Isolation and egress.

A fork pull request never runs

Cause. checks.forks: gated or trust: approve waits for approval, and forks: never skips it.

Fix. Click Approve run on the Slack message after reviewing the code. See Trust and forks.

Config is rejected

Cause. The file does not match the schema.

Fix. Run hookci validate. For a self-hosted hub also run hookci validate --self-hosted. See the .hookci.yml reference.

No messages in Slack

Cause. The channel is not bound, the repo is not watched, or the app was not invited.

Fix. In Slack run /hookci status, then /hookci watch owner/repo, and invite @hookci to the channel. See Slack.

A log link says expired

Cause. Signed log links last 15 minutes.

Fix. Open the run again from Slack App Home or the message to get a new link.

Exit codes

Full command list: CLI reference. Still stuck: [email protected], with the output of hookci doctor and hookci version.