Skip to main content

Troubleshooting

Diagnose and fix common issues when deploying and operating Reverse Proxy for ntfy.

DNS_PROBE_FINISHED_NXDOMAIN

Symptom: Browser or curl reports that the domain cannot be resolved.

Cause: The custom domain route was deployed but Cloudflare has not created the DNS record yet, or DNS has not propagated.

Solution:

  • Wait a few minutes after deployment — Cloudflare auto-creates DNS records for custom domain routes.
  • Check Dashboard > DNS > Records for a record matching your subdomain.
  • Check Dashboard > Workers & Pages > ntfy-reverse-proxy > Settings > Domains & Routes for the custom domain entry.
  • Verify propagation with dig {context-id}.ntfy.example.com.

ERR_SSL_VERSION_OR_CIPHER_MISMATCH

Symptom: Browser shows an SSL error when accessing a custom domain.

Cause: Cloudflare has not provisioned the SSL certificate for the new custom domain yet.

Solution:

  • Wait up to 15 minutes for certificate provisioning.
  • Check Dashboard > SSL/TLS > Edge Certificates for the certificate status.
  • Verify your SSL/TLS mode is "Full" or "Full (strict)" in Dashboard > SSL/TLS > Overview.

403 Forbidden (Cloudflare HTML Page)

Symptom: POST requests return a Cloudflare "Sorry, you have been blocked" HTML page instead of the worker's JSON response.

Cause: Bot Fight Mode or WAF rules are blocking automated HTTP requests (webhooks, curl, etc.).

Solution:

  • Disable Bot Fight Mode: Dashboard > Security > Bots > Bot Fight Mode > Off.
  • Or create a WAF skip rule: Dashboard > Security > WAF > Custom Rules:
    • If: (http.host contains "ntfy.example.com")
    • Then: Skip > All Super Bot Fight Mode Rules
    • Place at: First

warning

Bot Fight Mode cannot be skipped via WAF rules on any plan. The skip rule above targets Super Bot Fight Mode, which is available on Pro plans and above. Free plan users will need to disable Bot Fight Mode entirely if it blocks webhook traffic. You can also use a sec-fetch-mode header check to distinguish browser traffic from API traffic (see Security).

TLS Handshake Failure from Docker Containers

Symptom: Docker containers (e.g., Watchtower) fail with remote error: tls: handshake failure when sending to the proxy.

Cause: The container's CA certificate bundle is outdated. Cloudflare's edge certificates may chain through a CA that the container does not trust.

Solution: Mount the host's CA certificates into the container:

bash
docker run -v /etc/ssl/certs:/etc/ssl/certs:ro ...

On Synology NAS, the cert path is /etc/ssl/certs/. Add this volume mount and restart the container.

404 Not Found

Symptom: POST requests return a JSON error like {"status": "error", "message": "No context found for http identifier: ..."}.

Cause: The request subdomain does not match any configured context ID.

Solution:

  • Check that the context ID matches the subdomain: a request to abc123.ntfy.example.com needs a context with "id": "abc123".
  • Run nrp validate to check for config issues.
  • Re-deploy after config changes — the worker uses the copy of the config bundled into it at deploy time.
  • A POST to /session that answers Sessions are not enabled for this context means the context has no session field yet.

403 Authentication Failed

Symptom: POST requests return HTTP 403 from the worker with {"status": "error", "message": "Unauthorized"}.

Cause: The context has a token or session configured and the request does not include a matching Authorization header, or its session token is expired, already used, tied to another address, or session storage is unavailable.

Solution:

  • Include the header: Authorization: Bearer {context-token}.
  • Both Bearer {token} and raw {token} formats are accepted.
  • Check that the token matches exactly — it is case-sensitive.
  • With session set, get a fresh session token from /session for every message, and send both requests from the same IP address. The error-debug.json message names which check failed (see Session Tokens).

429 Too Many Session Requests

Symptom: POST /session returns HTTP 429 with {"status": "error", "message": "Too many session requests"}.

Cause: The IP address already got max_per_hour session tokens this hour.

Solution:

  • Wait for the next hour, or raise max_per_hour on the context and re-deploy.
  • Request a token only right before sending a message, rather than ahead of time.

422 Interpretation Failed

Symptom: POST requests return HTTP 422 with an error message from the interpreter.

Cause: The interpreter could not parse the request body. The payload does not match the expected shape for the configured interpreter.

Solution:

  • Check that the correct interpreter is configured for your webhook source.
  • For ntfy-json, verify the payload includes the required body field.
  • For service-specific interpreters, check that the payload matches the expected format (see individual interpreter docs).
  • For transmission-vpn, pfsense-actions, discord-stonker-bot, outpost, and mailmask, a message that starts with This context reads means the alert came from a different app. If the message names a supported interpreter, set the context's interpreter to it. If it says the app is unsupported, choose from the supported keys it lists or correct the producer's app field; do not configure the unknown key.
  • Read the message in the 422 response, which is the interpreter's error whether or not show_response_output is on. For the stack and the request as well, set an error_topic and keep interpretation in error_events.

Notifications Not Arriving

Symptom: The proxy returns 200 but notifications do not appear in ntfy.

Solution:

  • Check that the ntfy server is reachable and the token is valid.
  • Verify the ntfy server has behind-proxy set to true and base-url configured.
  • If the response is {"status": "ignored"}, the interpreter suppressed the notification on purpose, such as a duplicate or component-only Statuspage event (see Notification Suppression). Malformed JSON instead returns HTTP 422.
  • Enable show_response_output to see per-server delivery results in the response JSON.
  • Check ntfy server logs for authentication or topic permission errors.
  • For an error topic, verify attachment-cache-dir is configured on the ntfy server, because error details arrive as an error-debug.json attachment. Error-topic delivery is one-shot and best-effort, so a rejected attachment is not retried; importantly, it also cannot block the context's durable notification lane. Large text messages are handled by the proxy's message splitting and do not require this setting.

Queued or Discarded Durable Notifications

Symptom: A request returns {"status": "queued"}, later notifications for the same context wait, or an expected notification never arrives after the lane resumes.

Solution:

  • Look for a delivery_outbox_retry log event. It means the oldest notification had a transient network, HTTP 408, HTTP 429, or HTTP 5xx failure and remains queued. Its Durable Object alarm retries automatically with backoff; you do not need to post a dummy notification.
  • Look for a delivery_outbox_discarded log event. It means the row had a permanent failure or was still failing after it became at least 24 hours old and had at least three attempts. The event records deliveryId, classification, reason, httpStatus, attemptCount, and ageMilliseconds. A thrown configuration or JSON error has a null HTTP status.
  • Correct missing or renamed server entries and most HTTP 4xx responses before sending the notification again. Those failures are permanent and are discarded immediately so they cannot block the lane.
  • If the context has an error_topic, check it for a one-shot error-debug.json attachment titled "Durable Delivery Discarded." It contains delivery_id, reason, http_status, attempt_count, and age_ms. This diagnostic never enters the durable lane and is not retried if its own send fails.

Email Notifications Not Working

Symptom: Emails sent to {context-id}@{base_domain} do not produce notifications.

Solution:

  • Verify Cloudflare Email Routing is enabled for your domain.
  • Check that a routing rule exists for the email address pointing to your worker.
  • Verify the context type is "email" (not "http").
  • Check the allowed_from field — if set, the sender must match.
  • Email processing is silent — there are no HTTP error responses for failed email processing.

tip

If the context has an error_topic configured, authentication and interpretation errors from email processing are forwarded there as debug attachments. If the context also has an error_events setting, only the listed categories are forwarded. Check that topic for diagnostic information.

Duplicate Statuspage Notifications

Symptom: You receive the same Statuspage.io notification multiple times.

Cause: Without KV storage, the Statuspage interpreter cannot deduplicate updates. The interpreter compares the ID of the incident's latest update (incident.incident_updates[0].id) with the one it stored to detect duplicates.

Solution:

  • Run deploy (Deploy in the interactive menu or nrp deploy) — it automatically creates a KV namespace named {worker_name}-kv and binds it to the worker.
  • If you deploy with Wrangler yourself, add a [[kv_namespaces]] block with binding = "KV" and your namespace ID to wrangler.toml, because nrp generate leaves it out.
  • The interpreter stores incident state with a 24-hour TTL and skips duplicate update IDs.

405 Method Not Allowed

Symptom: Requests return HTTP 405 with a "Method not allowed" error.

Cause: The worker only accepts GET, POST, and PUT requests. Other HTTP methods (e.g., DELETE, PATCH) are rejected.

Solution:

  • Verify the webhook source is sending POST or PUT requests.
  • GET requests return the landing page, so use POST or PUT for webhook delivery.