# Troubleshooting

> A symptom index — find what you are seeing, jump to the check that resolves it. Organized by where the symptom appears.

[Canonical HTML page](https://safeonlineexam.com/docs/troubleshooting)

Troubleshooting is organized by **where you see the problem**: in the Canvas
launch, during authorization, in the detector on quiz pages, in SEB with the
configuration, or in the deployment itself. Find your symptom below and follow the
link.

## First, isolate the layer [#first-isolate-the-layer]

Before diving in, a 30-second triage narrows the search dramatically:

<Steps>
  <Step>
    ### Is the service healthy? [#is-the-service-healthy]

    ```bash
    curl -fsS "${TOOL_URL}/health"
    curl -fsS "${TOOL_URL}/ready"
    ```

    `/health` fails → the process is down. `/ready` fails → PostgreSQL is unreachable
    or migrations are not applied. Both are [deployment](/docs/troubleshooting/deployment)
    problems, not Canvas ones.
  </Step>

  <Step>
    ### Do the public endpoints respond? [#do-the-public-endpoints-respond]

    ```bash
    curl -fsS "${TOOL_URL}/lti/config"
    curl -fsS "${TOOL_URL}/.well-known/jwks.json"
    curl -fsS "${TOOL_URL}/js/canvas-seb-detector.js" | head
    ```

    If these fail, fix the deployment before touching Canvas.
  </Step>

  <Step>
    ### Where does it break for a user? [#where-does-it-break-for-a-user]

    Launch → [Canvas launch](/docs/troubleshooting/canvas-launch). "Connect Canvas"
    loops or scope errors → [OAuth & scopes](/docs/troubleshooting/oauth-scopes). Quiz
    page / detector → [Detector](/docs/troubleshooting/detector). Inside SEB / the
    `.seb` file → [SEB configuration](/docs/troubleshooting/seb-configuration).
  </Step>
</Steps>

## Symptom index [#symptom-index]

| Symptom                                           | Section                                                      |
| ------------------------------------------------- | ------------------------------------------------------------ |
| `sso.canvaslms.com refused to connect`            | [Canvas launch](/docs/troubleshooting/canvas-launch)         |
| `Canvas Signing-Key Error`                        | [Canvas launch](/docs/troubleshooting/canvas-launch)         |
| `Invalid LTI Launch`                              | [Canvas launch](/docs/troubleshooting/canvas-launch)         |
| `LTI Deployment Configuration Required`           | [Canvas launch](/docs/troubleshooting/canvas-launch)         |
| Administrator dashboard missing or denied         | [Canvas launch](/docs/troubleshooting/canvas-launch)         |
| A launch works in one environment but not another | [Canvas launch](/docs/troubleshooting/canvas-launch)         |
| A scope does not appear in the Developer Keys UI  | [OAuth & scopes](/docs/troubleshooting/oauth-scopes)         |
| Instructor is asked to authorize repeatedly       | [OAuth & scopes](/docs/troubleshooting/oauth-scopes)         |
| Student cannot connect Canvas / download fails    | [OAuth & scopes](/docs/troubleshooting/oauth-scopes)         |
| Detector never loads on quiz pages                | [Detector](/docs/troubleshooting/detector)                   |
| HTTP `422` on the theme JavaScript file           | [Detector](/docs/troubleshooting/detector)                   |
| Access code is not filled in SEB                  | [Detector](/docs/troubleshooting/detector)                   |
| Approved tools missing, or exit will not trigger  | [Detector](/docs/troubleshooting/detector)                   |
| SEB cannot open a downloaded configuration        | [SEB configuration](/docs/troubleshooting/seb-configuration) |
| A device fails after certificate rotation         | [SEB configuration](/docs/troubleshooting/seb-configuration) |
| Config Key proof fails after a settings change    | [SEB configuration](/docs/troubleshooting/seb-configuration) |
| Service fails to start / `/ready` never passes    | [Deployment](/docs/troubleshooting/deployment)               |
| Migration or cleanup job failures                 | [Deployment](/docs/troubleshooting/deployment)               |

## A note on error messages [#a-note-on-error-messages]

The tool shows deliberately specific error states — `sso.canvaslms.com refused to
connect`, `Canvas Signing-Key Error`, `Connect Canvas`, `Invalid LTI Launch`. Read
the exact text: it maps directly to a cause and a fix, which is why the launch
recovery table in [Self-hosted Canvas](/docs/canvas/self-hosted-canvas#launch-error-recovery)
and the sections here are keyed on it.