> ## Documentation Index
> Fetch the complete documentation index at: https://docs.roboticks.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Decision tree for common Roboticks issues - GitHub App webhooks, runner heartbeat, MCAP uploads, sim minute caps, requirement parsing.

# 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.

<Steps>
  <Step title="Confirm the App is installed on the repo">
    Dashboard → **Settings → Repositories** → look for the repo with status **Connected**. If missing, reinstall the GitHub App.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Check installation suspension">
    The App can be suspended by an org admin. Dashboard → **Settings → Integrations → GitHub App** → installation status.
  </Step>

  <Step title="Verify project linkage">
    Dashboard → **Repositories** → the repo must be linked to a project. If not, click **Link to project**.
  </Step>
</Steps>

Deep dive: [GitHub App → Troubleshooting](/github-app/troubleshooting).

## Test ran but no requirement was linked

Pytest passed; the matrix didn't update.

<AccordionGroup>
  <Accordion title="Is the SDK installed in the test environment?">
    Run `pip show roboticks` inside the runner's Python environment. If missing, add it to your test requirements.
  </Accordion>

  <Accordion title="Did the plugin load?">
    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`.
  </Accordion>

  <Accordion title="Are the `@confirms` properties in the JUnit XML?">
    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.
  </Accordion>

  <Accordion title="Does the requirement ID exist in the platform?">
    Dashboard → **Requirements** → search for the ID. A `@confirms("REQ-999")` on a non-existent requirement is silently no-op (logged as warning).
  </Accordion>
</AccordionGroup>

## Self-hosted runner shows offline

Heartbeat lapse for > 90 seconds marks the runner unhealthy.

<Steps>
  <Step title="Check the runner process">
    `systemctl status roboticks-runner` (Linux), `launchctl list | grep roboticks` (macOS), or Services panel (Windows).
  </Step>

  <Step title="Inspect runner logs">
    `journalctl -u roboticks-runner -n 200 -f` (Linux). Look for repeated connection errors → network problem; auth errors → token revoked, re-register.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Re-register if needed">
    `rbtk-runner register --project <slug> --pool <name>` with a fresh registration token.
  </Step>
</Steps>

Deep dive: [Runners → Troubleshooting](/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](/pricing) and [Runners → Pool Management](/runners/pool-management).

## MCAP upload fails

The test ran but evidence is missing the MCAP.

<AccordionGroup>
  <Accordion title="Presigned URL expired">
    Presigns are 15 min. Multi-GB MCAPs over slow uplinks may exceed that. Reduce MCAP size with a [topic allowlist](/sdk/mcap-capture), or request an extended presign window (Enterprise).
  </Accordion>

  <Accordion title="Disk full on runner">
    MCAPs are buffered locally before upload. Free up space; check `df -h` on the runner host.
  </Accordion>

  <Accordion title="mcap extra not installed">
    The MCAP context manager no-ops silently without the optional dep. Install with `pip install 'roboticks[mcap]'`.
  </Accordion>
</AccordionGroup>

## Requirement parsing failed

PDF or ReqIF upload returned an error.

<AccordionGroup>
  <Accordion title="PDF: LLM extraction returned zero requirements">
    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.
  </Accordion>

  <Accordion title="ReqIF: schema validation failed">
    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](/requirements/reqif).
  </Accordion>

  <Accordion title="YAML: schema validation failed">
    Run `rbtk requirements validate roboticks/requirements.yaml` for line-level errors. Schema: [requirement.schema.json](https://github.com/roboticks-io/roboticks-sdk/blob/main/schemas/requirement.schema.json).
  </Accordion>
</AccordionGroup>

## 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](/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

<CardGroup cols={2}>
  <Card title="GitHub App troubleshooting" icon="github" href="/github-app/troubleshooting">
    Webhook deliveries, installation health, Check Run problems.
  </Card>

  <Card title="Runner troubleshooting" icon="microchip" href="/runners/troubleshooting">
    Heartbeat, capability matching, MCAP uploads, version skew.
  </Card>

  <Card title="Networking FAQ" icon="network-wired" href="/networking-faq">
    Firewall rules, proxies, air-gapped mode.
  </Card>

  <Card title="Email support" icon="envelope" href="mailto:hello@roboticks.io">
    Team and Enterprise customers.
  </Card>
</CardGroup>