Troubleshooting RelayBridge

Start with bounded evidence

1. Open Diagnostics locally and record the status and evidence source.
2. Confirm the RelayBridge Windows service is Running.
3. Check management, actual SMTP binding, queue worker, Microsoft runtime readiness, certificate, storage, and disk capacity separately.
4. Run the non-authenticated Exchange connectivity check for DNS, TCP, or TLS investigation.
5. Use Microsoft Verify connection for active certificate, token, TLS, and XOAUTH2 validation.
6. Generate and review a support bundle only when the collected evidence is needed for a report.

RelayBridge service is not running

Symptoms: the desktop shortcut cannot open the UI, Diagnostics is unavailable, or Windows Services shows RelayBridge stopped.

Check: start the RelayBridge service in Windows Services; review the Windows Application event log for RelayBridge or .NET startup errors; verify the production override is valid; confirm ProgramData access and free space; use installer Repair if installed files are missing or altered.

Do not: repeatedly delete and recreate the service, replace installed binaries manually, relax ProgramData ACLs, or erase the database or spool.

Management UI is unavailable

Symptoms: the shortcut times out or the local page does not load.

Check: service state; local http://localhost:5080/health; whether another process occupies the management port; Windows Application events; and installer Repair for opener or registry state.

Do not: bind management to a LAN address or create a firewall rule for port 5080. Remote management is not supported.

Printer cannot connect or SMTP is refused

Symptoms: the device reports timeout or connection refused and no local acceptance appears.

Check: the actual listener binding in Settings; whether the selected interface remains active; the device port; listener and queue readiness; trusted-LAN routing; the narrow Windows Firewall rule if required; and whether connection limits are exhausted.

Do not: use 0.0.0.0, a public address, an Internet-facing firewall rule, or expose the management endpoint.

Device authentication fails

Symptoms: the local SMTP session receives a 535-class authentication rejection.

Check: the device is enabled; username and one-time password were copied exactly; the password was not reset; source IP matches the rule; the client uses AUTH LOGIN or AUTH PLAIN; and connection security is None.

Do not: change to Legacy mode only to bypass a credential problem. Use Legacy mode only when the device truly lacks SMTP AUTH and strict source isolation is acceptable.

Sender is rejected

Symptoms: MAIL FROM is rejected before durable queuing or upstream delivery.

Check: the SMTP envelope sender—not just the header From—matches the device sender rule and active Microsoft sender; Microsoft setup is active and verified; and the sender is a real Exchange Online mailbox.

Do not: broaden to a wildcard sender or add broad tenant permissions.

Microsoft setup is incomplete

Symptoms: the dashboard says Not configured, Verification required, or setup can be resumed.

Check: return to Microsoft 365 setup; inspect the safe stage, substage, category, and code; confirm the original candidate, certificate, and sender are unchanged; and resume the wizard. After a service restart, use direct Verify connection for the active configuration.

Do not: paste raw tokens or output into public reports, delete a working active configuration, or rerun tenant provisioning through unrelated scripts.

Exchange SMTP 535

Symptoms: Microsoft identity is ready but Exchange Online rejects XOAUTH2 authentication.

Check: tenant and mailbox SMTP AUTH policy; application identity and certificate match; Exchange service-principal reference; effective Application SMTP.SendAsApp scope for the sender; certificate time validity; and the safe Step 5 details.

If this is the exact eligible post-provisioning case, allow the bounded Step 5 checks to run. SMTP 535 can also have permanent causes; propagation is not assumed.

Do not: retry every 535 indefinitely, enable Basic Auth, grant Graph mail permissions, or replace the candidate during an automatic session.

Waiting for Exchange authorization

Symptoms: Step 5 shows an Active automatic verification session, attempt and next-check fields, and Authentication · SMTP 535.

Check: leave the page open for the five-minute scheduled checks; use Check now for one non-overlapping immediate attempt; and confirm the candidate has not changed. The session ends after 12 automatic attempts or one hour.

Do not: promise a propagation duration, continuously click controls, or assume success before normal verification activates the candidate.

Queue is not delivering

Symptoms: local SMTP succeeds but ready, retrying, or permanent-failure counts remain, or the worker is not running.

Check: Queue.Enabled and worker status; current-process Microsoft readiness; certificate access; oldest message and next retry; disk capacity; Exchange connectivity; and permanent-failure classification. Restart after changing deployment configuration.

Do not: delete spool files or edit SQLite directly. Local 250 means RelayBridge owns a durable copy that must be handled deliberately.

DNS, TCP, or TLS verification fails

Symptoms: the Diagnostics connectivity probe stops at DNS, TCP 587, greeting, EHLO, STARTTLS, or TLS.

Check: DNS resolution, outbound TCP 587, Windows system time and trust store, TLS inspection, proxy or firewall policy, and Exchange service availability. The probe does not authenticate or send mail.

Do not: disable certificate or hostname validation or switch the Microsoft-facing hop to cleartext SMTP.

Windows Firewall blocks the printer

Symptoms: the service listens on the selected interface, but intended devices cannot reach it.

Check: the network profile is Private; the rule targets the exact Host executable, local address, printer port, and source device or subnet; endpoint security has no conflicting policy; and VLAN routing permits the path.

Do not: enable all profiles, ports, or programs or expose the listener to public networks.

Update check fails

Symptoms: Settings reports that it could not check for updates.

Check: HTTPS access to the GitHub API, DNS, system time, proxy policy, GitHub availability, and a later manual retry.

The manual check is informational. Failure does not make the Windows service, SMTP listener, queue, Microsoft configuration, or delivery path unhealthy.

Repair or uninstall issue

Symptoms: installed files or shortcut remain missing after repair, or the service remains after normal uninstall.

Check: use the original supported bootstrapper; review its log; reboot if Windows servicing requests it; and verify service, Program Files, URI registration, and shortcut state. Remember that ProgramData, certificates, and tenant objects are intentionally retained.

Do not: manually delete the service or protected data before preserving evidence and confirming normal Windows servicing failed.

Deeper diagnostic guides