Skip to main content

​
Troubleshooting

Decision tree for the most common failures. If your issue isn’t here, see the deeper guides linked at the bottom or open a support ticket.

​
GitHub Check Run never appears

The PR was opened but the Roboticks Check Run is missing.
1

Confirm the App is installed on the repo

Dashboard → Settings → Repositories → look for the repo with status Connected. If missing, reinstall the GitHub App.
2

Inspect webhook deliveries

In GitHub: Repo settings → Webhooks → Roboticks → recent deliveries. A 2xx means we received it. 4xx usually means the webhook secret rotated. 5xx is our side — open a ticket.
3

Check installation suspension

The App can be suspended by an org admin. Dashboard → Settings → Integrations → GitHub App → installation status.
4

Verify project linkage

Dashboard → Repositories → the repo must be linked to a project. If not, click Link to project.
Deep dive: GitHub App → Troubleshooting.

​
Test ran but no requirement was linked

Pytest passed; the matrix didn’t update.
Run pip show roboticks inside the runner’s Python environment. If missing, add it to your test requirements.
Run pytest with -p roboticks.pytest_plugin -v and look for the plugin banner. If pytest reports it as unknown, the package didn’t install the entry point — reinstall with pip install --force-reinstall roboticks.
Inspect the JUnit file at <runner-workdir>/junit.xml. Look for <property name="roboticks.confirms" value="REQ-001"/>. If missing, the decorator isn’t actually applied — check for typos and import order.
Dashboard → Requirements → search for the ID. A @confirms("REQ-999") on a non-existent requirement is silently no-op (logged as warning).

​
Self-hosted runner shows offline

Heartbeat lapse for > 90 seconds marks the runner unhealthy.
1

Check the runner process

systemctl status roboticks-runner (Linux), launchctl list | grep roboticks (macOS), or Services panel (Windows).
2

Inspect runner logs

journalctl -u roboticks-runner -n 200 -f (Linux). Look for repeated connection errors → network problem; auth errors → token revoked, re-register.
3

Confirm outbound 443

curl -I https://api.roboticks.io/healthz from the runner host. If a proxy is in the path, confirm HTTPS_PROXY is set in the runner’s environment.
4

Re-register if needed

rbtk-runner register --project <slug> --pool <name> with a fresh registration token.
Deep dive: Runners → Troubleshooting.

​
Sim minutes cap reached

A hosted job was rejected with HTTP 402.
  • Free tier hard cap is 30 sim minutes/month — no overage. Upgrade or move the job to a self-hosted runner (always free).
  • Team tier auto-bills overages at $0.10/min above the 500 included.
  • Check current usage: dashboard → Billing → Usage or rbtk pool usage.
See Pricing and Runners → Pool Management.

​
MCAP upload fails

The test ran but evidence is missing the MCAP.
Presigns are 15 min. Multi-GB MCAPs over slow uplinks may exceed that. Reduce MCAP size with a topic allowlist, or request an extended presign window (Enterprise).
MCAPs are buffered locally before upload. Free up space; check df -h on the runner host.
The MCAP context manager no-ops silently without the optional dep. Install with pip install 'roboticks[mcap]'.

​
Requirement parsing failed

PDF or ReqIF upload returned an error.
The PDF may be image-only (scanned) without OCR. Pre-OCR with ocrmypdf input.pdf output.pdf and re-upload. Or copy-paste the text into the dashboard requirement editor.
Validate locally with rbtk requirements validate path/to/export.reqif. Common issues: missing IDENTIFIER, unmapped SPEC-OBJECT-TYPE, vendor-specific custom datatypes. See ReqIF round-trip.
Run rbtk requirements validate roboticks/requirements.yaml for line-level errors. Schema: requirement.schema.json.

​
Evidence pack generation stuck

A rbtk test evidence-pack call is taking longer than expected.
  • Typical generation time: 30 seconds for small releases (< 100 tests), up to 10 minutes for large packs with many MCAPs and a heavy SBOM.
  • Check status with rbtk test evidence-pack status <pack-id>.
  • If failed, inspect the Lambda log link in the response. Common cause: a missing artifact (the runner crashed before uploading).
Deep dive: Evidence → Generation.

​
Cross-cutting tips

  • Always check the dashboard’s Audit Log first (Settings → Audit Log) — many issues correlate with a recent action.
  • rbtk doctor prints a one-shot health check of your local environment (auth, network, SDK install).
  • Discord support is the fastest channel for non-urgent issues.

​
Where to look next

GitHub App troubleshooting

Webhook deliveries, installation health, Check Run problems.

Runner troubleshooting

Heartbeat, capability matching, MCAP uploads, version skew.

Networking FAQ

Firewall rules, proxies, air-gapped mode.

Email support

Team and Enterprise customers.