forgerunner/docs/troubleshooting.md

Troubleshooting

Symptom-driven guide for common runner failures.

---

Runner not appearing in Gitea admin panel

Check: Container logs for registration errors.

docker logs gitea-runner 2>&1 | grep -E "BOOTSTRAP|FATAL|ERROR"

Common causes:

Cause	Fix
GITEA_RUNNER_TOKEN is invalid or expired	Generate a fresh token in Gitea admin → Runners
GITEA_INSTANCE_URL wrong or unreachable	Verify URL is reachable from inside the container: docker exec gitea-runner curl -I "$GITEA_INSTANCE_URL"
TLS cert error (self-signed Gitea)	Mount your CA cert to /config/trusted-ca/ and restart
Runner name already registered	Use a unique GITEA_RUNNER_NAME or deregister the old one

---

node: not found in job logs

The runner image bundles Node.js 20 LTS. If you see this error it usually means:

• The job is running inside a container image that does not have Node.js (e.g. alpine).
• The ubuntu-latest label is mapped to a minimal image.

Fix: Ensure the label mapping uses a full Node image:

ubuntu-latest:docker://node:20-bullseye

Or use a host-mode label:

ubuntu-latest:host

---

Docker socket permission error

Symptom:

permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock

Causes and fixes:

Cause	Fix
Socket not mounted	Add -v /var/run/docker.sock:/var/run/docker.sock
Socket GID mismatch	Container runs as root in v1 — this should not occur. If using a non-root custom image, add the runner user to the docker group or set --group-add $(stat -c '%g' /var/run/docker.sock)

---

Workflow checkout failures

Symptom: actions/checkout fails with an auth or host error.

Check:

1. Gitea URL is accessible from inside the container.
2. If using self-signed TLS, the CA cert is trusted inside the container.

docker exec gitea-runner curl -v https://git.example.com

If you see certificate errors, add your CA cert to /config/trusted-ca/ and restart.

---

Registry login failures (docker/login-action)

Symptom: Login to registry.alwisp.com fails.

Check:

1. Registry URL is correct.
2. Credentials are valid.
3. If using self-signed TLS on the registry, the CA cert needs to be trusted inside the container AND the Docker daemon config must also trust the registry.

For Docker daemon CA trust on the Unraid host:

mkdir -p /etc/docker/certs.d/registry.alwisp.com
cp my-ca.crt /etc/docker/certs.d/registry.alwisp.com/ca.crt

Then restart the Docker daemon and the runner container.

---

Container job image issues

Symptom: Jobs that run inside container images fail to pull or execute.

Check:

• The container image referenced in the label mapping is pullable from inside the runner container.
• If using a self-hosted registry image, the runner container can authenticate to it.

---

CA / certificate trust issues

Symptom: TLS errors when connecting to Gitea or the registry.

Fix:

1. Copy your CA cert (.crt format, PEM encoded) to config/trusted-ca/.
2. Restart the container — the entrypoint installs certs from that directory on startup.
3. Verify: docker exec gitea-runner curl -v https://git.example.com should show cert chain OK.

---

Unraid-specific: container exits immediately

Check: Container logs before exit:

docker logs gitea-runner

Look for [FATAL] lines. Common cause is a missing required env var (GITEA_INSTANCE_URL, GITEA_RUNNER_TOKEN, GITEA_RUNNER_NAME) when no config file exists.

Fix: Set required env vars in the Unraid container template.

---

Startup validation failures

Symptom: Container exits with [FATAL] Missing required binaries.

This is an image build problem — the binary should always be present if the image was built correctly.

Fix: Rebuild the image from the docker/runner/Dockerfile and verify:

./scripts/verify-runtime.sh custom-gitea-runner:latest