Troubleshooting

Where to look when something is not working. Start from the symptom: the headings below are ordered by "what is not happening", and each one works from the most common cause to the rarest.

#Do this first: verify the install

In the panel, Settings → Install → Verify install. Our server actually downloads your page and runs eleven separate checks, then tells you which step is missing. Most problems show up here, and it is far quicker than guessing.

Check results come in three colours. Only three checks block sending: APP_ID, SDK and SERVICE_WORKER. The rest are warnings — worth fixing, but they do not stop delivery.

#Check codes

#APP_ID — "The app ID is missing or wrong"

No data-key was found on the page. You may have forgotten the script tag, or a plugin removed it. View the page source (Ctrl+U) and search for data-key.

#APP_ID — "The key on the page does not belong to this project"

There is a key on the page, but it belongs to another project. If you have several projects in the panel you may have copied the wrong one. Get the right key from Settings → Install.

#SDK — "The Web Push SDK was not found"

The script tag is not on the page. Common causes:

• The code was added to the home page only, and you verified on a different page.
• A theme update reverted your header.php change. On WordPress, install the plugin — it survives theme updates.
• A caching plugin is serving old HTML. Clear the cache and try again.
• The page content is rendered later by JavaScript. Our checker looks at the HTML the server returns, so the script has to be printed server-side.

#SDK_SOURCE — the "loading from a local copy" warning

A JS-combining plugin (Autoptimize, LiteSpeed Cache, WP Rocket, Cloudflare Rocket Loader) has copied the SDK onto your own server. Notifications keep working, but security updates never reach you — you are using a frozen copy.

The fix: exclude cdn.bildirim.io/sdk.js from that plugin's combining/optimisation. Our WordPress plugin adds the necessary markers (data-no-optimize, nowprocket) by itself.

#SERVICE_WORKER — "found at the root but the SDK does not load it from there"

You put the file in your site's root directory. It has to be in the /bildirim/ folder:

https://yoursite.com/bildirim/BildirimSDK-sw.js   ✓ correct
https://yoursite.com/BildirimSDK-sw.js            ✗ does not work

This is a rule, not a preference: the SDK registers the service worker under the /bildirim/ scope and never loads a file from anywhere else. Move the file and verify again.

#SERVICE_WORKER — "not found"

The file is missing, or your server is not serving it. Open it directly in a browser: https://yoursite.com/bildirim/BildirimSDK-sw.js. The expected content is a single line. If you cannot see it:

• Make sure you uploaded it to the right folder (the wrong FTP directory is the most common mistake).
• Check that your server serves .js files from that folder — some security plugins block JS outside the root.
• The address must be https. Push does not work without a secure connection.
• If you use Cloudflare, purge the cache.

#SW_CONFLICT — "another service worker was found"

Your site still has a service worker from OneSignal, Firebase or another push tool. This produces the quietest and most maddening failure mode: the subscription is recorded, the notification never arrives. A browser allows one service worker per scope; the older one shadows the new one.

Remove the old tool's files (OneSignalSDKWorker.js, firebase-messaging-sw.js, a root-level sw.js) from your site. After removal, the registration lives on in visitors' browsers for a while; in your own browser, use developer tools → Application → Service Workers → Unregister.

#The MANIFEST warning

Affects iPhone and iPad only. Without a manifest, Chrome, Edge, Firefox and Android work normally; iOS users cannot receive notifications because Apple requires the site to have been added to the home screen. If iOS does not matter to you, you can ignore this warning.

#The CLOUDFLARE warning

Your site is behind Cloudflare. Our checks may be restricted (bot protection can stop us downloading the page). If verification keeps failing and you are sure the code is right, allow the Bildirim-InstallChecker user agent in Cloudflare, or verify on a page where bot protection is off.

#I cannot send

#"The install must be verified for … before sending" (domain_unverified)

A new project needs its install verified before live sending. Complete Settings → Install → Verify install. The gate stays shut until the three blocking checks above are green.

#"You must send a test notification before your first live send" (no_test_send)

Use the Send test button on the notification screen once. This gate exists on purpose: we do not want the first notification to a real audience to come out of an install that has never been tried. A test send also requires the install to be verified.

#"Your monthly send quota … is full" (send_quota_exceeded)

Your plan's monthly send allowance is used up. The quota counts by UTC calendar month and resets on the 1st.

There are no partial sends: if a send would exceed the quota, the whole thing is rejected. That is deliberate — a random slice of your list receiving a notification is worse than none of it. You can see what is left on the Overview → Usage card; an email warning goes out at 80%.

#"Subscriber limit reached for this plan" (quota_exceeded)

You have hit the subscriber limit; new subscribers cannot be recorded. Existing subscribers can still re-register and sending is not stopped. Upgrade the plan or clean out inactive subscribers.

#"This project has been deleted" (project_deleted)

The project is being deleted; there is a 30-day undo window. Restore it from Projects → Deleted.

#No subscribers are being collected

The permission prompt never appears.

• Are you opening the page over https? Push does not work on http or file://. localhost is the exception.
• If you previously declined permission for this site in the browser, the prompt is never shown again. Reset the permission from the padlock icon in the address bar.
• You may already be subscribed. Try a private window.
• If a delay (delaySeconds) is configured under Settings → Permission prompt, the prompt appears that many seconds later.
• If the script tag has data-auto-prompt="false", the prompt never appears; you have to call Bildirim.subscribe().

It does not work in Safari. macOS Safari 16.1+ is supported. On iPhone/iPad the site must have been added to the home screen — Apple's rule, not our limitation.

There are fewer subscribers than I expected. On a normal website, 2–10% of visitors grant permission. After installing, the count only grows as visitors come back to the site.

#The notification was sent but never arrived

If the panel says "sent", the notification was delivered to the browser's push server. After that, four things can happen:

1. Another service worker got in the way. The most common cause. See the SW_CONFLICT section above.

2. The device is off or offline. Push servers hold the notification for a while and it arrives when the device comes back. Chrome's default retention is four weeks.

3. The operating system is suppressing notifications. Focus Assist on Windows, Do Not Disturb on macOS, battery optimisation on Android. Even when the site's permission looks granted in the browser, the system can suppress it.

4. The user turned it off in browser settings. In that case the subscription is treated as invalid on the next send and deactivated automatically.

Test on yourself: the Send test button on the notification screen sends only to your own subscription. If the test arrives but the campaign does not, the problem may be your segment — check the targeted subscriber count in the send report.

#The quiet numbers: what the report shows

"Sent" is not a delivery guarantee; it says the notification reached the browser's server. That is the nature of web push, and no provider can know more than that.

A high "failed" count is usually good news: the list is cleaning itself. A persistently high rate points to an old list you have not sent to in a long time.

#The wrong campaign went out

Notifications that have been sent cannot be recalled. All you can do is stop what has not gone yet: Notifications → the notification → Stop. The system tells you how many sends were cancelled and how many had already gone.

On large lists sending takes minutes, so if you act quickly you can stop most of it. Following up with a short correction to the same segment is common and well accepted.

#An API key has leaked

Settings → Keys → Rotate. A new key is created immediately and the old one keeps working for a while (60 minutes by default) — enough time to update your integrations without an outage.

In an emergency press Revoke: it becomes invalid at once and every integration using it starts getting 401. Who did what and when is recorded under Settings → Security → Security activity.

#My webhook is not working

No requests arrive at all. Your address has to be reachable from outside; private network addresses such as localhost or 192.168.* are rejected for security. Make sure the webhook is enabled and that you selected the right events.

Signature verification does not match. The signed text is the triple timestamp.deliveryId.rawBody. The most common mistake is parsing the body as JSON and re-serialising it — the bytes change and the signature no longer matches. Use the raw body. Detail and sample code: Using the API.

A delivery shows as "dead". All five attempts failed and it will not be retried. Your server must return 2xx within 15 seconds. If the work takes longer, queue the request and answer immediately. If the address stays dead for 24 hours, an alert appears in the panel.

#RSS automation is not working

"A feed address must be a public http(s) address" — you entered a private network address. 403 / 429 — your own server is blocking us. Allow us through your firewall. "Unreadable content" — the address returns HTML instead of XML, or the feed is malformed. Open it in a browser and check.

When a feed fails repeatedly the system slows down but does not give up; once the feed recovers it continues by itself and you do not need to do anything.

#Is something wrong on your side?

The bildirim.io/en/durum page shows the live state of the database, the queue, the send worker and the email component.

An honest warning: that page runs inside the infrastructure it reports on. If everything goes down it cannot answer — it is not an independent status page.

#Still stuck?

Write to us from the panel with Support → New request; the reply appears both on that screen and in your email, and the whole conversation stays on record. If you prefer, you can also write directly to [email protected]. Including the following greatly increases the chance of it being solved on the first reply:

• The project name and site address
• The output of the install verification screen (a screenshot is enough)
• The id of the problem notification, or the time it was sent
• If you use the API, the full body of the error you received (the error and message fields)