Troubleshoot Relay

Use the symptom that matches the visible Relay state. Preserve the selected organization, mailbox, actor, and channel boundary while diagnosing it. Do not repair a user-owned WhatsApp inbox with organization-wide settings controls.

Relay redirects to account onboarding

The platform onboarding gate runs before Relay. Complete the account profile with both first and last name, then return to Relay. A confirmed account, organization membership, or copied Relay URL does not bypass this profile requirement.

Relay does not open the expected organization

Relay excludes organizations where the account is only a guest. With one available organization it selects that workspace automatically; with multiple organizations it requires Select an organization.

1. Return to https://relay.infra.one/.
2. If Open organization selector appears, choose the intended organization.
3. Check that the organization shown in the Relay URL is one where the signed-in account has a current member or administrator membership, not a guest membership.
4. Navigate to the channel from Relay instead of reusing a mailbox, connection, or chat identifier from another organization.

If the account has no non-guest membership, it has no Relay workspace. A route or query parameter cannot substitute for membership.

Email is missing

Only organization administrators receive Relay Email read, send, and attachment-download capabilities. An ordinary member can see Relay and use their own WhatsApp connection but cannot read or open Relay Email. A system administrator who is only an ordinary member also does not gain Email capability.

Confirm the selected organization and membership role. If the role recently changed, return to the Relay overview and reopen the organization. Do not use an Email thread or attachment URL as an access workaround.

No mailbox is available

No mailbox yet means Relay found no active mailbox assigned to the selected organization. No mailbox selected means accessible mailboxes exist but none is currently selected. This mailbox is not available in this Relay workspace. means the requested mailbox ID is not in the accessible set.

1. Open Mailbox and choose an available address.
2. If the list is empty, ask the authorized mailbox administrator to check the mailbox status and organization or vehicle assignment outside Relay.
3. Do not create or reassign a mailbox merely to produce a screenshot or test result.

The Email list may be stale

Check the health label and callout:

• Healthy exposes no current warning.
• Never synced or Sync not started means the first sync has not completed.
• Degraded or Sync is degraded means some threads may be stale.
• Sync unknown or Sync needs attention means Relay cannot establish mailbox health.

Use Refresh only when you are authorized to trigger a provider sync. A successful refresh reports the provider result and reloads the local list; it is not proof that every provider record is current.

Search or a view shows no Email threads

1. Clear Search emails….
2. Confirm the selected Mailbox.
3. Return to Inbox, then check Sent, Failed, Archived, Done, Unread, or With attachments as appropriate.
4. Review mailbox health before concluding that a thread does not exist.

Each view or search exposes at most the 50 most recent matching threads. Relay applies the selected view and search before that limit, and the current list does not provide pagination or Load more. Search is a case-insensitive substring match across subjects, message text, sender names or addresses, recipient names or addresses, and attachment filenames. Switching the view clears the search. To find an older thread, narrow the view or search so it falls within the newest 50 matches. If it still does not appear, the current list cannot expose it; ask support to verify its safe, non-sensitive identifiers instead of guessing a provider URL.

The Drafts view is a special current limitation. Relay creates and autosaves actor-owned drafts, and closing or choosing Save for later preserves the draft itself. However, the Drafts view does not list durable drafts: its thread query is forced empty and its count is hardcoded to zero. IO-11441 tracks the defect. Do not promise draft recovery through that view, and do not create a duplicate send solely because the list is empty.

A draft does not save

• Draft save failed can mean validation, storage, or actor/mailbox access failed.
• Cannot save the draft. It changed in another session — close and reopen it. means optimistic locking detected a stale editor.
• Draft not found can mean the draft was discarded, belongs to another actor, or is no longer accessible through the selected mailbox.

Stop editing after a conflict. Preserve the visible content separately only if policy permits, close the composer, and ask support to inspect the actor-owned draft. The empty Drafts view is not a recovery method while IO-11441 remains open.

Email cannot be sent

If Compose or a reply control is disabled, check the tooltip:

• Cannot start an email. Select a mailbox first. means no mailbox is selected.
• Cannot send from this mailbox yet. It is not verified for outbound email. means the mailbox lacks verified send status.
• You are not authorized to send from this mailbox means the current account lacks the required capability.

Before retrying validation, confirm at least one valid To recipient, the intended subject and body, and attachments within the limits. Relay accepts up to 10 files. No individual file may exceed 25 MiB, and all files together must stay within 25 MiB.

An Email send failed

Queued the email for delivery proves a durable outbox item was queued, not that the provider delivered it. An open thread with Last send failed can offer Retry send when the item is retryable.

A provider grant can still fail during the later delivery attempt even after Relay accepted the queue request.

The Failed view filters synchronized EmailMessage error state; it does not guarantee visibility of an actor’s local outbox failure or retry status. A compose failure before an Email message projection exists need not appear there or expose list-based recovery. If the open thread does not expose the expected outbox status, obtain support or status confirmation before creating a replacement draft or retrying.

1. Review the safe failure message, recipient, content, and mailbox verification.
2. Confirm that the outbox item still represents the intended send.
3. Select Retry send once. Relay queues another attempt on the same item and idempotency key.
4. Wait for a later delivery state. Do not create a new draft as a substitute for inspecting the failed item.

If Relay says the state no longer allows retry, reload the thread before taking another action.

An Email attachment is unavailable

• Pending means the bytes have not finished syncing.
• Blocked means safety checks refused the file.
• Available is required for View, Download, and Save to vehicle documents.

Save to vehicle documents also requires the message’s trusted vehicle context. If Relay says the attachment is not linked to a vehicle, do not infer one from the sender, filename, or thread subject.

WhatsApp has no conversations or cannot send

The WhatsApp inbox lists only connections owned by the signed-in user in the selected organization. Another administrator’s connection does not become shared.

1. Confirm the selected organization and signed-in account. Opening the inbox can resume resumable authentication and synchronize stale avatar or group metadata, so do not use it as a passive capture check.
2. Clear Search conversations… and select All.
3. Check the connection indicator. Persisted messages remain available when disconnected or relink is required, but new messages, groups, and reactions are disabled.
4. If the chat came from an old or copied URL, return to the WhatsApp list. Chat not found can mean it is not owned through the current user’s connection.

Do not ask an administrator to use another user’s connection. WhatsApp’s ordinary inbox ownership is per user, not per organization.

If Create group rejects the selected participants, do not treat picker visibility as proof that they are valid group recipients. Group creation needs at least one candidate that resolves to a valid direct-user JID, and a displayed broadcast or channel candidate can still be rejected at submission. Preserve the non-sensitive error and ask support to confirm the participant type instead of trying unrelated conversations.

Link to contact is missing or finds no person

Link appears only for an unmatched, non-group conversation that is not the connected account’s self-chat. A conversation already linked to a Contacts person does not expose it.

In Link to contact, enter at least two characters from the person’s name or email. Results contain only Contacts people from the current organization and stop at 10 matches. If Relay reports No contacts found, refine the name or email; do not create a duplicate contact or send a WhatsApp message merely to force a result. A successful selection reports Linked NAME, persists the local association, and removes the conversation from Unmatched without contacting the WhatsApp provider.

WhatsApp settings or recovery looks inconsistent

IO-11440 tracks a product conflict: inbox and event authorization require a current-user-owned connection, but settings loads the latest organization connection without the inbox’s current-user ownership check. Its provider process is keyed by the organization, and merely mounting the settings page can start or resume work.

The visible actions require special caution:

• Reset connection has no confirmation and immediately clears credentials before restarting pairing.
• Retry history sync stops and resumes the organization-keyed runtime.
• Delete all WhatsApp data confirms the click but deletes organization-wide WhatsApp connections and cascading conversations, messages, reactions, participants, and Signal sessions. CRM contacts remain.

Until IO-11440 is resolved, do not use pairing, reset, retry, or delete controls as a documented recovery path. Preserve the visible non-sensitive error and contact support with the organization, signed-in actor, connection state, and time. Do not include QR codes, phone numbers, message content, credentials, or customer identifiers.

Relay says WhatsApp or Telegram is shared

IO-11439 tracks stale channel and inbox ownership copy. Current source registers Email and WhatsApp only:

• Email is a shared, organization-scoped administrator workspace.
• WhatsApp is the signed-in user’s own connection and inbox inside the selected organization.
• Telegram is not currently shipped.

Follow those implemented boundaries rather than the stale summary. Do not use the old copy as authorization to open another person’s WhatsApp data or promise a Telegram workflow.

Relay reports that access changed

Relay rechecks the selected organization and connection for channel events. Your Relay access changed means the current connection no longer satisfies that check.

Return to the Relay overview, reselect the organization, and confirm the current role and connection owner. Do not continue by editing the URL or retrying a mutation from stale browser state.

Related pages

• Relay overview
• Review a shared Relay Email inbox
• Use Relay Email and WhatsApp
• Relay permissions and states