> ## Documentation Index
> Fetch the complete documentation index at: https://fit4lifecare.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshoot Common Fit4Life OS Issues

> Fix the most common problems in Fit4Life OS: SMS not delivered, orders not appearing, export failures, login issues, and bot not responding.

Use this guide to diagnose and resolve the most frequent issues clinic operators encounter in Fit4Life OS. Each entry describes the likely cause and the steps to fix it. Work through the causes in order, most issues are resolved by the first or second check.

<AccordionGroup>
  <Accordion title="SMS replies are not delivered to the customer">
    If a customer reports that they did not receive your reply, check each of the following causes in order:

    **Cause A, Customer is opted out.** The customer previously texted STOP, which blocks all outbound messages to their number. Ask the customer to text START to re-opt in.

    **Cause B, Inbound webhook not configured.** If your Twilio Messaging Service does not have `UseInboundWebhookOnNumber` set to `true`, inbound messages route nowhere and the bot never replies. In your Twilio console, open the Messaging Service settings and enable that option.

    **Cause C, Message too long / encoding.** Long replies are automatically split into multiple SMS segments, and non-GSM-7 characters are transliterated to keep messages single-byte, so a single oversized message can no longer be dropped by the carrier. If splitting is not occurring, confirm your deployment is running the latest version.

    **Cause D, A2P campaign status.** Outbound application-initiated SMS routes through the A2P Messaging Service. Confirm your campaign is approved and `TWILIO_MESSAGING_SERVICE_SID` is set in production.
  </Accordion>

  <Accordion title="&#x22;Send Failed&#x22; appears in the inbox composer">
    A "Send Failed" banner means the manual reply did not go out. Follow these steps:

    1. Re-send by composing the message again, transient issues usually clear on a second try.
    2. Confirm the customer's phone number is valid (a real 10-digit US mobile).
    3. Confirm the Twilio + Messaging Service configuration is active. If sessions have expired (they last 24 hours), reload and log back in.

    Historically the most common cause was a backend bug (a numeric thread key), now fixed, a genuine failure today is a carrier, number, or configuration issue.
  </Accordion>

  <Accordion title="Order not visible in Finances or order count">
    If an order is missing from Finances or the order count looks wrong, check the order's status first.

    Open **Orders** and locate the order. If its status is `pending_payment`, it is intentionally excluded from all revenue analytics until the customer pays. This is by design, revenue is only recognized on committed (`paid`) orders.

    Once the customer completes payment on the checkout page, the charge is confirmed synchronously and the status changes to `paid` on the spot, the order appears immediately in Finances, P\&L, and all related reports. If the customer has paid but the order still does not appear, refresh the view.
  </Accordion>

  <Accordion title="Bot is not responding to customer texts">
    If customers are texting your number and receiving no reply, work through these checks:

    1. **Webhook URL**: In your Twilio console, verify the inbound webhook is set to `https://<your-deployment-url>/api/sms/webhook`.
    2. **UseInboundWebhookOnNumber flag**: In the Messaging Service settings, confirm this flag is `true`. When a number is in a Messaging Service, the service controls inbound; without this flag, messages are received but routed nowhere.
    3. **Anthropic API key**: Confirm `ANTHROPIC_API_KEY` is set and the account has remaining credits. A depleted or invalid key causes the bot to fail.
  </Accordion>

  <Accordion title="Export download is empty or fails">
    If an export file downloads with no data, or the download fails entirely, try the following:

    1. **Broaden the date range**: The most common cause of an empty export is a range that contains no matching records. Switch to **All Time** and re-export to confirm there is data.
    2. **Switch file formats**: If the download itself fails, try a different format (for example, CSV instead of XLSX) to isolate whether the issue is format-specific.
    3. **Check your browser's download permissions**: Some browsers block automatic downloads. Look for a blocked-download notification and allow the file.
  </Accordion>

  <Accordion title="The AI assistant isn't saving my changes">
    The assistant requires your explicit confirmation before it writes any change. After you ask it to make a change, look for the **preview card** in the assistant panel, it describes exactly what will be changed.

    Click **Confirm** on that card to apply the change. If you close the card, navigate away, or ignore it, nothing is saved. If no preview card appeared, rephrase your request with more specifics (the customer's name, the exact field) and try again.
  </Accordion>

  <Accordion title="Customers added via the OS aren't recognized by the bot">
    The SMS bot identifies customers exclusively by phone number. If a customer you added is not being recognized when they text in, open **/live/customers**, find that customer, click **Edit**, and confirm a valid 10-digit mobile number is saved in the phone field. The bot recognizes the customer on their next inbound text.
  </Accordion>

  <Accordion title="Referral tree is empty or flat">
    The referral tree is built solely from the **Referred by** field on each customer profile. If the tree is flat, those fields have not been filled in yet, the platform does not infer relationships.

    To build the tree, open a customer's profile, click **Edit**, set the **Referred by** field to the customer who referred them, and save. Repeat for each referred customer. There is no bulk import, each relationship is set on the individual profile.
  </Accordion>
</AccordionGroup>