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
- If:
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:
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.comneeds a context with"id": "abc123". - Run
nrp validateto check for config issues. - Re-deploy after config changes — the worker uses the copy of the config bundled into it at deploy time.
- A
POSTto/sessionthat answersSessions are not enabled for this contextmeans the context has nosessionfield 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
sessionset, get a fresh session token from/sessionfor every message, and send both requests from the same IP address. Theerror-debug.jsonmessage 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_houron 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 requiredbodyfield. - 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, andmailmask, a message that starts withThis context readsmeans the alert came from a different app. If the message names a supported interpreter, set the context'sinterpreterto it. If it says the app is unsupported, choose from the supported keys it lists or correct the producer'sappfield; do not configure the unknown key. - Read the
messagein the 422 response, which is the interpreter's error whether or notshow_response_outputis on. For the stack and the request as well, set anerror_topicand keepinterpretationinerror_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-proxyset totrueandbase-urlconfigured. - 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_outputto 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-diris configured on the ntfy server, because error details arrive as anerror-debug.jsonattachment. 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_retrylog 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_discardedlog 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 recordsdeliveryId,classification,reason,httpStatus,attemptCount, andageMilliseconds. A thrown configuration or JSON error has anullHTTP 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-shoterror-debug.jsonattachment titled "Durable Delivery Discarded." It containsdelivery_id,reason,http_status,attempt_count, andage_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_fromfield — 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}-kvand binds it to the worker. - If you deploy with Wrangler yourself, add a
[[kv_namespaces]]block withbinding = "KV"and your namespace ID towrangler.toml, becausenrp generateleaves 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
POSTorPUTrequests. GETrequests return the landing page, so usePOSTorPUTfor webhook delivery.