Notification troubleshooting¶
Applies to: Owner, Administrator, support staff, server administrators. Last reviewed: 2026-11-18.
Each problem below lists the causes that follow from the code, where to look, and the fix. School staff can do everything marked "School". Items marked "Platform" need the DriveFlow server administrator.
1. Start here¶
flowchart TD
A["A message did not arrive"] --> B{"Is this a message DriveFlow sends at all?<br/>(see Notification triggers)"}
B -- yes --> C["Settings > System > Notification Log:<br/>search the email address or phone number"]
C --> F["Row says Failed"]
C --> S["Row says Sent"]
C --> N["No row"]
F --> F1["Read the error; fix the cause; resend manually"]
S --> S1["Left DriveFlow.<br/>Check spam, the address, the phone"]
N --> N1["Not attempted: switched off, quiet hours,<br/>missing address, plan, or job not running"]
The first question is answered in Notification triggers.
Remember
- Nothing is retried automatically (except the daily payment reminder, which tries again the next day after a failed email).
- "Sent" means the provider accepted it, not that the person read it.
- A message that was skipped leaves no row in the log; the reason is in the server log only.
2. Emails not delivered¶
| Symptom | Cause | Where to look | Fix |
|---|---|---|---|
| No row in the log for any automatic email | Email master switch is off | Settings > Notifications > Notification Channels | School: switch Email on, Save Changes |
| No row for one type of message | That message's Enabled switch or Email tick is off | Settings > Notifications > Student Notifications | School: switch it on |
| No row; nothing at all is sent for the school | The school has no notification settings yet | Server log: "notifications are not configured or not active" | School: open Settings > Notifications once (this creates the defaults) and save |
| No row for a Student Welcome | Sent during quiet hours, which drops it | Settings > Notifications > Quiet Hours | School: narrow the quiet window. The welcome is not sent later. |
| No row for a booking or payment message | The student or instructor has no email address | The student's or instructor's record; server log "has no Email address" | School: add the address. The message is not sent afterwards. |
| No "Payment Received" email for a walk-in customer | By design: there is no student to address | - | School: use Email Receipt on the payment |
| No email to the instructor after changing the instructor | The reschedule message goes to the instructor the lesson had before the change | - | Tell the new instructor directly |
| Row says Failed with an SMTP sign-in error | The school's own SMTP username or password is wrong or expired | Settings > Email; hover the Failed chip | School: correct the details, Save Changes, Send Test Email |
| Failed: "SMTP port 465 (implicit SSL) is not supported..." | Port 465 entered | Settings > Email | School: use port 587 with Use SSL / TLS on |
| Failed with a timeout | Mail server unreachable (30 second limit) | Hover the Failed chip | School: check the host name and port. Platform: check the global mail server. |
| Failed: sender refused | The mail server does not allow the Sender Email | Settings > Email | School: use an address the mailbox may send as |
| Row says Sent but the student has nothing | Spam folder, typing error in the address, or the receiving server dropped it | The Recipient column in the log | School: correct the address on the record and resend manually. Consider your own SMTP server so mail comes from your domain. |
| "This student has no email address. Add one to their profile and try again." | Manual send with no address | - | School: add the address |
| "This customer has no email address on the invoice." | Walk-in invoice without an email | - | School: add it to the invoice |
| "A cancelled invoice cannot be emailed." | The invoice is cancelled | - | - |
| New user says no password email came | These emails are not in the log; failures are only in the server log ("Unable to send the account password e-mail to ...") | Server log | School: reset the user's password to send a new one |
| Portal invite: "The portal sign-in was created, but the invite email could not be sent. Try Resend invite." | Email failed after the account was made | - | School: fix email settings, then click Resend invite |
| No password reset email | Unknown or inactive account; more than 3 requests in 15 minutes; or Platform:AppUrl not set |
Server log: "Password reset email throttled" or "Platform:AppUrl is not set" | Wait 15 minutes. Platform: set the app URL. |
| School's SMTP ignored; mail comes from DriveFlow | Custom SMTP not saved as enabled, or the saved password could not be decrypted | Settings > Email shows "DriveFlow Default"; server log "Failed to decrypt SMTP password" | School: re-enter the password and save |
| Subscription invoice email not received | The organisation has no email address | Message "Your organisation has no email address. Add one under Settings > Organisation and try again." | School: add it, then resend from Settings > Billing |
3. SMS not sent¶
| Symptom | Cause | Where to look | Fix |
|---|---|---|---|
| Failed: "No SMS credits left. Buy an SMS bundle under Settings > Billing." | Balance lower than the parts this message needs | Notification Log; Settings > Billing | School: buy a bundle. Unsent messages are not sent afterwards. |
| SMS switch is disabled with "You have no SMS credits left..." | Credits at 0 on a paid plan | Settings > Notifications | School: buy a bundle |
| SMS switch disabled with "SMS is not included in your plan..." | Plan does not include SMS | Settings > Subscription | School: upgrade |
| No SMS rows at all, email rows present | SMS master switch off, or the SMS box not ticked for that message | Settings > Notifications | School: switch on and tick |
| No SMS for Invoice Issued or Lesson Completed | These are never sent by SMS | - | - |
| No SMS row for one person | No phone number on the record | Record; server log "has no Sms address" | School: add the number |
| Failed: "'...' is not a valid destination number." | Number has no digits | Record | School: correct it |
| SMS went to the wrong country | A foreign number stored without + and country code gets 27 added |
Record | School: store as +<country code><number> |
| Failed: "Vodacom SMS send failed with status ..." | Provider refused (credentials, sender id, account) | Hover the Failed chip | Platform: check the VodacomSms settings and the provider account |
| Failed: "Vodacom SMS is enabled but no credentials are configured." | Platform configuration incomplete | - | Platform |
| Log says Sent, nobody receives SMS, credits go down | The provider is switched off on the server (VodacomSms:Enabled false) |
Server log: "[SMS disabled] Vodacom SMS is not enabled" | Platform: enable the provider |
| Credits run out faster than expected | Messages are 2 or more parts (160 / 153 characters; 70 / 67 with special characters) | Open a row to see the full text | School: tick SMS only for the messages that matter |
| Payment reminder SMS missing | The reminder email failed first, the invoice is a walk-in, or the run was in quiet hours | Notification Log | Fix the email problem; check quiet hours |
4. WhatsApp failing¶
| Symptom | Cause | Where to look | Fix |
|---|---|---|---|
| Failed: "Meta WhatsApp send failed with status 400 ..." mentioning 131047 or re-engagement | The 24-hour rule: free-form text is only allowed within 24 hours of the person's last message to the business number. DriveFlow has no approved templates. | Hover the Failed chip | None in the current version. Use email or SMS for these messages. |
| Failed with 401 / token error | Access token expired or wrong | - | Platform: renew the token |
| Failed: "...access token or phone number id is not configured." | Platform configuration incomplete | - | Platform |
| Switch disabled: "WhatsApp is a paid add-on. Activate it under Settings > Billing to use it." | Add-on not paid or lapsed | Settings > Billing | School: pay for the add-on |
| Switch disabled: "WhatsApp is not included in your plan..." | Plan | Settings > Subscription | School: upgrade |
| No WhatsApp rows | Master switch off, box not ticked, or no phone number | Settings > Notifications; record | School |
| Log says Sent, nothing arrives | Provider switched off on the server | Server log: "[WhatsApp disabled]" | Platform |
| WhatsApp stopped after a month | The add-on's paid period ended; the channel is dropped silently | Settings > Billing | School: renew |
Most WhatsApp failures come from the 24-hour rule
There is no fix for it in the current version. See WhatsApp notifications section 3.
5. Push not appearing¶
| Symptom | Cause | Where to look | Fix |
|---|---|---|---|
| No push rows for anyone | Firebase not configured, or the plan has no Mobile App | Server log: "Push notifications are off: ..." | Platform: configure Firebase with a readable key and restart the API (DriveFlow support). School: check the plan. |
| No push row for one person | They have no phone registered: not signed in to the app, push switched off in the app's Settings, or signed out | - | Ask them to sign in and switch notifications on in the app |
| Instructor gets nothing | The instructor profile is not linked to a user account | Instructor record | School: link or invite the instructor |
| Row says Sent, nothing on the phone | Android notification permission refused, battery restrictions, or the phone is offline | Phone settings | Allow notifications for DriveFlow |
| Failed: "Push notification not delivered: ..." | Firebase refused every device (wrong project, bad key) | Hover the Failed chip | Platform: check that the app build and the server key belong to the same Firebase project |
| Push stopped after reinstalling the app | The old token was removed; a new one is registered at the next sign-in | - | Sign in again |
| Push for invoices never comes | Invoice Issued is email only | - | - |
| Phone used by two people shows the wrong person's alerts | A phone belongs to whoever signed in last | - | Each person uses their own phone |
6. Duplicates¶
| Symptom | Cause | Fix |
|---|---|---|
| Student gets a server reminder plus two reminders from the phone | The mobile app schedules its own reminders (18:00 the evening before and one hour before) on top of the server's | The student can switch the phone's lesson reminders off in the app's Settings |
| Email and push and SMS for the same event | Each enabled channel sends its own copy | Untick the channels you do not want |
| Two reminders for one lesson | The lesson was rescheduled after the first reminder; a new reminder is sent for the new time | Expected |
| Two reminders for a double lesson | Each lesson of the block is reminded separately | Expected |
| Invoice email and a "Note from your school" naming the same invoice | An extra lesson was approved: the invoice email and the booking confirmation are separate messages | Expected |
| Two payment reminders close together | A manual Send Reminder plus the automatic one | Manual reminders count towards the maximum but do not move the due-soon reminder |
| Welcome email twice at school registration | It goes to the school's email and the owner's email when they differ | Expected |
The reminder jobs cannot send the same reminder twice for the same start time, and the invoice job cannot send the same stage twice; see Lesson reminders.
7. Delays and wrong times¶
| Symptom | Cause | Fix |
|---|---|---|
| Reminder up to 15 minutes late | The job runs every 15 minutes | Expected |
| Reminder arrives in the morning instead of at night | Held by quiet hours and sent at the first run after they end | Expected; change the quiet window if needed |
| Reminders an hour or two early or late | The server clock is in a different time zone from the branch; the reminder code uses the server's clock | Platform: run the API in the schools' time zone |
| Quiet hours seem shifted | Same cause | Platform |
| Payment reminders arrive at 10:00, not 08:00 | The daily job is scheduled without a time zone, so Hangfire uses UTC | Platform decision |
| No reminder for a lesson booked today for tomorrow morning | The lesson was created after its reminder time; the booking confirmation stands in for it | Expected |
| No reminder although the lesson is tomorrow | Lesson status is not Scheduled; or Lesson Reminder is off; or the first reminder attempt failed (it is not retried) | Check the lesson status, the settings and the log |
| Saving a booking is slow | Messages are sent inside the request; a slow mail server (up to 30 seconds) or SMS/WhatsApp provider (15 seconds each) delays the response | Platform: check provider response times |
8. Background jobs not running¶
| Symptom | Cause | Where to look | Fix |
|---|---|---|---|
| No reminders of any kind | The API is stopped; Hangfire runs inside it | Server status | Platform: start the API |
| Reminders stopped after a deployment | Job registration failed at start-up | Server log: "Failed to register Hangfire recurring jobs at startup." | Platform: check the database connection and restart |
| Invoices not becoming Overdue | The invoice-reminders job is not running (it also sets the status) |
Server log: "Running Invoice Reminder Job at ..." each day | Platform |
| One lesson never reminded | An error for that lesson | Server log: "Failed to send reminder for Lesson ..." | Platform: read the error |
| One invoice never reminded | An error for that invoice, or no email address on it | Server log: "Failed to process payment reminder for invoice ..." | School: add the address |
| Document expiry reminders never arrive | Not working in the current version | Lesson reminders section 5 | Check expiry dates by hand |
| Trial ended without warning | No warning emails exist | - | Watch the banner in the app |
Job monitoring: the DriveFlow platform team can see the recurring jobs, their last and next run, and failed runs with its own monitoring tools. Schools do not have access to it.
Server log categories and dispatcher log lines (for the platform team)
Server log categories to filter on (class names): NotificationDispatcher, LessonReminderJob, DrivingTestReminderJob, InvoiceReminderJob, InvoiceReminderService, InvoiceEmailService, TenantSmtpEmailService, VodacomSmsService, MetaWhatsAppService, FirebasePushSender, PasswordRecoveryService, UserService, StudentPortalAccessService, RegistrationEmailService, SubscriptionInvoiceEmailService, DocumentExpiryJob.
Dispatcher log lines:
| Text | Meaning |
|---|---|
| "Notification {Event} skipped: no tenant in scope." | Raised without a school; a code problem |
| "... skipped for company ...: notifications are not configured or not active." | No settings row, or inactive |
| "... skipped for company ...: event disabled." | The message's Enabled switch is off |
| "... skipped for company ...: quiet hours." | Non-urgent message inside quiet hours |
| "... skipped for company ...: no channel enabled." | Every channel off or not covered by the plan |
| "... skipped for company ...: no recipient could be resolved." | No student or instructor (for example a walk-in payment) |
| "... recipient ... has no ... address." | Missing email or phone number |
| "... SMS skipped, no credits left." | Out of credits |
| "Notification {Event} sent. ..." / "Notification {Event} failed. ..." | Outcome per channel |
| "Notification pipeline failed for {Event} ..." | Unexpected error; the business action still succeeded |
9. Resending¶
| Message | How to resend |
|---|---|
| Invoice | Invoice menu > Send Email |
| Payment reminder | Invoice menu > Send Reminder |
| Receipt | Payment menu > Email Receipt |
| Quote | Send the quote again |
| Portal invite | Student page > Resend invite |
| User password | Reset the user's password under Settings > Users |
| Subscription invoice | Settings > Billing, send on the invoice |
| Booking confirmation, cancellation, reschedule, reminder, welcome, lesson completed | Cannot be resent. Contact the person directly. |
Engine messages cannot be resent
Booking confirmations, cancellations, reschedules, reminders, welcome messages and lesson-completed messages have no resend button. Contact the person directly.