# Troubleshooting

> Common problems, their causes, and how to fix them.

Web page: https://infrainbox.app/docs/help/troubleshooting/

## "I didn't get a notification"

Work through it in order — each step narrows down where it stopped:

1. **Did the event arrive at all?** Check **Activity** (dashboard screen `/events`) for it. If it's not there, the problem is upstream: the sender, its key, its URL, or the network between them and InfraInbox — see the specific errors below.
2. **Did it open or update an incident?** If the event shows a `disposition` other than `incident` (`inbox` or `dropped`), no notice was ever due — check what rule matched it. Low-severity events (`INFO`, `SUCCESS`, `DEBUG` by default) are inbox-only, not incidents.
3. **What did the rule do with it?** Use [dry run](https://infrainbox.app/docs/notifications/dry-run.md) with a similar event to see, without sending anything, which rule matches and what it decides.
4. **Was a notice held back?** A silence, a mute, quiet hours below the destination's threshold, or a cooldown (repeat occurrences of an already-open incident) can all record a notice as **skipped** rather than sent — check [Silences and mutes](https://infrainbox.app/docs/notifications/silences.md) and [Quiet hours](https://infrainbox.app/docs/notifications/quiet-hours.md).
5. **Did the delivery itself fail?** Check **Deliveries** (dashboard screen `/deliveries`) (set **Status** to Failed) or the incident's timeline in the Inbox, which lists every notice with its destination and status; **Deliveries and full details** shows the error and offers **Retry**. A notice whose destination has since been deleted is listed as **Deleted destination**.

## A source is stuck on a connection state

- **Waiting for first request** — nothing has reached it yet. Double-check the URL and key you gave the sender.
- **Reachable, but no real events after 48 hours** — the source's own "Test" succeeded, but nothing real has followed. This is almost always a problem on the sender's side: its matcher, filter, or notification mode isn't actually routing real events to InfraInbox. The source's own page calls this out directly.
- **Unknown** — not enough information yet to say either way; this isn't itself a problem.

## Errors from the events API

| Status | Code | Likely cause |
|---|---|---|
| 401 | `unauthenticated` | The key is missing, malformed, wrong, or revoked. Check the `Authorization: Bearer iik_src_…` header. |
| 403 | `forbidden` / `credential_not_accepted` | The credential is valid but not for this operation — for example a heartbeat token sent to the events endpoint. |
| 413 | `payload_too_large` | The request body is over 2 MiB. Send fewer events per batch, or trim `body`/`metadata`. |
| 422 | `validation_failed` | A field failed validation — the response's `errors` array names which one and why. |
| 422 | `idempotency_mismatch` | An `Idempotency-Key` (or an event's own `idempotencyKey`) was reused with a different body. Use a new key per distinct request. |
| 429 | `rate_limited` | Too many requests too fast. Wait for the number of seconds in the `Retry-After` header before retrying. |

## Telegram says "chat not found"

The bot's chat ID is wrong, or the bot was removed from the chat/group/channel. Re-open the destination, use **Find my chats** again (message the bot at least once first, so Telegram has something to show), and re-select the chat. Until it's fixed, the destination reports a broken health and its notices are held rather than dropped silently.

## The Proxmox test fails

- **Unknown issuer / certificate error** — the server's TLS certificate isn't trusted by Proxmox (typically the app's self-signed default). Either put a browser-trusted certificate in front of it (see [TLS and reverse proxies](https://infrainbox.app/docs/self-hosting/reverse-proxy.md)) or import the certificate into Proxmox's trust store.
- **401** — the webhook secret pasted into Proxmox doesn't match the source's current key. Re-copy it from the source's setup page; if the key was rotated, Proxmox needs the new one.
- **Timeout** — Proxmox can't reach the server at all: check the URL, firewall rules and that the port is open from the Proxmox host.

## The phone gets nothing

Confirm the destination that should have fired includes InfraInbox Push (check the rule or the default route), that the phone is still paired (Settings → Devices), and that the incident's severity clears the destination's own quiet-hours threshold if you're inside quiet hours. See [iPhone app and push](https://infrainbox.app/docs/notifications/mobile-app.md).

## The clock or time zone looks wrong

Quiet hours and a rule's time conditions are evaluated in the **workspace's** time zone (Settings → Workspace), not your browser's or the server host's. If an event's own timestamp is more than 7 days in the past or more than 5 minutes in the future compared to when InfraInbox received it, InfraInbox replaces it with the time it was received and flags the event `clock_skew` — check the sending host's clock if you see this often.

## Locked out / lost your authenticator

If you still have a recovery code (ten were shown once when you enabled two-factor authentication, each works once), use it at sign-in instead of a code from your authenticator app. Once signed in, regenerate a fresh set from Settings → Security so you're not left with fewer next time.

> **Warning:** If you've used every recovery code and lost the authenticator too, there's no self-service way back into that account today — check with whoever else administers your instance.