IncidentRelay
Static Documentation

Troubleshooting

Version latest · Updated 2026-09-12
Interactive docs View on GitHub

Troubleshooting#

500 on duplicate names or slugs#

Duplicate resources should return 409 Conflict, not 500. Check API logs for IntegrityError and add explicit error handling in the corresponding view.

Common examples:

  • duplicate group slug;
  • duplicate team slug;
  • duplicate service slug inside the same team;
  • duplicate channel name inside the same team.

Empty body returns unclear validation error#

POST/PUT endpoints should return a structured 400 validation_error when body is missing or invalid JSON.

Calendar invalid date returns 500#

Query parameters such as start and end should be validated before date parsing reaches business logic.

Email test works but real alert does not#

Check:

  • Real alert has an assignee.
  • Assigned user has email in profile.
  • Channel is attached to the matched route.
  • Severity filter allows the alert severity.
  • SMTP relay accepted and delivered the message.

Voice call fails with missing phone#

Voice call sends to the assigned user's profile phone number. Set phone on the assigned user.

Telegram token error#

Telegram bot token must contain a colon:

123456789:AA...

If the token is invalid, fix the channel config or disable the channel.

Reminders are duplicated#

Check that only one scheduler process is running and that scheduler is not started inside every web worker.

Alert is not visible#

Check:

  • The correct route intake token was used.
  • The endpoint matches the route source.
  • Route matchers match alert labels.
  • The group is active.
  • The team is active.
  • The UI active group is correct.
  • All my groups is selected when the alert can belong to another accessible group.
  • routing_error in the integration response.
  • JSON logs by error_id if the server returned one.

Alert has no service#

If an alert is created but service is empty:

  • Check that the route has a default service.
  • Check that a service match rule exists.
  • Check that the service match rule is enabled.
  • Check that the rule is scoped to the correct route, or has no route scope.
  • Check that labels, annotations or payload fields match the rule.
  • Check that the service and owning team are enabled.

Example Alertmanager service match rule:

{
  "labels": {
    "job": "RabbitMQ",
    "rabbitmq": {
      "op": "regex",
      "value": "^rabbitmq-cloud$"
    }
  }
}

Check:

  • The alert has service_id.
  • The service link or runbook is enabled.
  • The service link or runbook is not deleted.
  • The runbook matchers are empty, or they match the alert labels/annotations/payload.
  • The notification formatter supports service context for the selected channel.

Runbook matcher behavior:

empty matchers -> generic runbook for all alerts of the service
matchers set -> only matching alerts

Browser push is disabled or VAPID public key is not configured#

Check the profile config endpoint:

GET /api/profile/push/vapid-public-key

Expected response:

{
  "enabled": true,
  "public_key": "B..."
}

If enabled is false or public_key is null, fix the [browser_push] config and restart the web service. Restart the scheduler too if it sends notifications in your installation.

Browser push test works but real alert does not#

Test push sends to the current profile user. Real alert push sends to alert.assignee_id.

Check:

  • The alert has an assignee.
  • The assignee is the same user who enabled push in Profile.
  • The subscription row has enabled = true and deleted = false.
  • Browser push is enabled in config.
  • /service-worker.js is current in the user's browser.

Browser push is not a channel, so it does not appear in route channel bindings.

Browser push action returns token_expired#

The one-time ACK/Resolve/Shelve/Unshelve token was older than [browser_push] action_token_ttl_seconds when the browser sent the action.

Browser push action returns token_already_used#

The same notification action token was already consumed. This can happen after a double click, browser retry, or clicking the same notification action more than once.

Service, team or group name shows as -#

Display code should use this order:

name -> slug -> "-"

For links and runbooks, make sure serializers include:

service_id
service_name
service_slug
team_id
team_name
team_slug