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

# HubSpot sync failures

> Diagnose missing HubSpot form submissions, stalled workflow actions, and contact property updates that never reach HubSpot from Flowella, and how to fix them.

Most HubSpot issues fall into one of three buckets: the **integration is disconnected**, a **field mapping is wrong**, or a **workflow action is misconfigured**. This page works through them in order.

For initial setup, see [HubSpot setup](/hubspot/setup). For workflow actions, see [Workflow actions](/hubspot/workflow-actions).

## 1. Check the connection

<Steps>
  <Step title="Open Settings → HubSpot">
    From the Flowella app, go to **Settings → HubSpot**.
  </Step>

  <Step title="Read the status badge">
    A green **Connected** badge means the OAuth token is valid. A red **Reconnect** banner means the token has been revoked or expired.
  </Step>

  <Step title="Reconnect if needed">
    Click **Reconnect** and run through HubSpot OAuth again. Then retry the failing action.
  </Step>
</Steps>

<Info>
  Common causes for a HubSpot connection going bad:

  * The HubSpot user who authorised Flowella was removed from the portal.
  * HubSpot rotated the token because it had not been used recently.
  * A Super Admin disabled the Flowella integration in HubSpot's app settings.
</Info>

## 2. Form submissions not appearing in HubSpot

If a contact completes a WhatsApp Flow but you can't see the submission in HubSpot:

### Field mapping mismatch

The Flow may include a field that doesn't map to a HubSpot property of a compatible type. Open the form on the [Forms](/app/forms) page and review the mapping for each field.

### Required field is empty

If a HubSpot form field is marked required and the WhatsApp Flow allowed the user to skip it, the submission will be rejected by HubSpot. Make the field optional in HubSpot, or required in the Flow.

### Phone number format

HubSpot is strict about phone format. See [Phone number format](/hubspot/phone-number-format) — most "missing contact" issues come down to E.164 vs national format.

### Lookup happens after the workflow action runs

If your HubSpot workflow runs immediately on form submission, race conditions can cause the workflow to fire before Flowella has finished writing the contact. Add a short delay (1–2 minutes) at the start of the workflow, or trigger off the contact property change instead of the form submission.

## 3. Workflow actions stalled or failing

If a HubSpot workflow that includes a Flowella action is stuck:

### Open the workflow's Action history

In HubSpot, find the contact, scroll to **Workflow History**, and click into the failing run. HubSpot shows the response Flowella returned for each action.

### Common error responses

| Error                   | What to do                                                                                                                                          |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Channel not found`     | The workflow points at a channel that no longer exists. Edit the action and pick a current channel. See [Multi-channel](/essentials/multi-channel). |
| `Template not approved` | The template referenced has changed status to `REJECTED`, `PAUSED`, or `DISABLED`. See [Template rejected](/troubleshooting/template-rejected).     |
| `Contact opted out`     | The contact has opted out on this channel. Honour the opt-out — do not work around it.                                                              |
| `Phone number invalid`  | The contact's phone is not in E.164. See [Phone number format](/hubspot/phone-number-format).                                                       |
| `Subscription required` | Your Flowella plan does not include this action, or your subscription has lapsed. See [Billing](/account/billing).                                  |

### Action exists but does nothing

If the workflow runs without errors but no message arrives, double-check:

* The action is enabled (not paused).
* The recipient is enrolled in the workflow at the right step.
* HubSpot's enrolment criteria still match the contact.

## 4. Sync direction confusion

Flowella sync is **bidirectional but partial**:

* WhatsApp Flow submissions → write contact properties to HubSpot.
* HubSpot workflow actions → send WhatsApp messages and templates.
* Inbound WhatsApp replies → log to the contact timeline (does not auto-update properties).

If you expected a free-form WhatsApp reply to update a property, that needs an extra step on your side — a HubSpot workflow that watches for the conversation event and parses the reply, or a custom integration via the [API](/api-reference/introduction).

## Still stuck?

<Note>
  Capture the following before contacting [support](https://flowella.io/support):

  * The **last sync** timestamp from **Settings → HubSpot**
  * The exact error message (or screenshot) Flowella or HubSpot returned
  * The affected contact ID and workflow ID
</Note>