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

# HubSpot troubleshooting

> Diagnose and fix failed HubSpot syncs, step by step.

Every sync attempt is recorded on the **Sync History** tab of the HubSpot integration page. Failed jobs show a plain-language explanation of what went wrong, a **Retry** button, and — when the cause is on our side — a **Report an issue** button that opens a support ticket with the technical details already attached.

## How to debug a failed sync

<Steps>
  <Step title="Open Sync History">
    Go to **Integrations → HubSpot → Sync History**. Find the job marked **Error** — it shows which lead failed and when.
  </Step>

  <Step title="Read the error">
    Each failed job displays a short title and a description telling you what to fix. Hover over the message to see the raw technical error HubSpot returned — useful if you want to look it up or share it with support.
  </Step>

  <Step title="Apply the fix">
    Look up the error title in the [error reference](#error-reference) below and follow the fix.
  </Step>

  <Step title="Verify with a test lead">
    On the **Overview** tab, select **Send test lead**. This validates every mapped property against your live HubSpot account and creates a disposable test contact — without touching real leads. If the test passes, your configuration is fixed.
  </Step>

  <Step title="Retry the job">
    Back in **Sync History**, select **Retry** on the failed job. With Auto-Sync on, future edits to the lead also trigger a fresh sync.
  </Step>
</Steps>

<Tip>
  The test contact is created with an email like `caard-test+…@example.com`, so it's easy to find and delete in HubSpot afterwards.
</Tip>

## Error reference

These are the exact error titles you'll see on a failed job in Sync History.

<AccordionGroup>
  <Accordion title="HubSpot isn't connected">
    **What it means:** There is no active HubSpot connection for this workspace — it was never set up, or it was disconnected.

    **How to fix:** Go to **Integrations** and select **Connect** on the HubSpot card, then retry the sync.
  </Accordion>

  <Accordion title="Your HubSpot connection needs to be reconnected">
    **What it means:** Caard couldn't reach HubSpot with the stored credentials. The authorization has expired or was revoked — for example, the connecting user left the HubSpot portal, their permissions changed, or the app was uninstalled from HubSpot's **Connected Apps** settings.

    **How to fix:**

    1. Go to **Integrations** and select **Connect** on the HubSpot card.
    2. Sign in to the **same HubSpot portal** as before (the portal ID is shown on the Overview tab).
    3. Approve all requested permissions.
    4. Retry the failed jobs from Sync History.

    Reconnecting keeps all your field mappings, settings, and sync history.
  </Accordion>

  <Accordion title="HubSpot is missing some permissions">
    **What it means:** The connection exists, but it wasn't granted every permission Caard needs. This usually happens when individual scopes were declined during authorization, or when a HubSpot admin later restricted the app.

    **How to fix:** Reconnect from the Integrations page and approve **every** requested permission. Caard needs read/write access to contacts, companies, and lists, plus read access to owners. If your HubSpot user can't grant these, ask a HubSpot super admin to connect instead.
  </Accordion>

  <Accordion title="This contact already exists in HubSpot">
    **What it means:** HubSpot already has a contact with this email (or phone), and **Deduplicate contacts** is turned off — so Caard refused to create a duplicate.

    **How to fix:** Enable **Deduplicate contacts** under **Advanced Config** on the Overview tab, then retry — the existing contact is updated instead. If you genuinely want a second contact, leave deduplication off and resolve the conflict in HubSpot first.
  </Accordion>

  <Accordion title="HubSpot is rate-limiting us">
    **What it means:** HubSpot received too many API requests in a short window. This is normal during large bulk syncs and resolves on its own.

    **How to fix:** Usually nothing — Caard [retries automatically](#rate-limits-and-automatic-retries). If the job has exhausted its automatic retries, wait a minute and select **Retry**.
  </Accordion>

  <Accordion title="A mapped field doesn't exist in HubSpot">
    **What it means:** One of your field mappings points to a HubSpot property that doesn't exist in your account. The error names the offending property. Common causes: a typo in the internal name, using the display label instead of the internal name, or the property was deleted in HubSpot.

    **How to fix:**

    1. Open the **Field Mapping** tab (or **Company Mapping** for company errors) and find the named property.
    2. In HubSpot, go to **Settings → Properties** and check the property's **internal name** — for example `lead_source_detail`, not "Lead Source Detail".
    3. Correct the mapping, or create the property in HubSpot, or disable the mapping.
    4. Use **Send test lead** to confirm — it checks every mapped property against your live HubSpot account and flags any that don't exist.
  </Accordion>

  <Accordion title="A field value was rejected by HubSpot">
    **What it means:** A property exists, but HubSpot rejected the value Caard sent. The most common case is a dropdown (enumeration) property that only accepts a fixed set of options — if the Caard value isn't one of them, the whole sync fails. Format mismatches (e.g. sending text to a number or date property) cause this too.

    **How to fix:** Hover over the error to see which property and value HubSpot rejected. Then either:

    * Add the value as an option on the property in HubSpot (**Settings → Properties → edit the property's options**), or
    * Remap the Caard field to a free-text property, or
    * Fix the value on the lead itself.
  </Accordion>

  <Accordion title="This lead has no email">
    **What it means:** HubSpot uses email as the primary identifier, and the lead has none. By default Caard skips these leads, because contacts without an email are hard to find and dedupe in HubSpot.

    **How to fix:** Add an email address to the lead and retry. If you want email-less leads synced anyway, enable **Sync leads without an email** under **Advanced Config** — optionally together with **Deduplicate by phone fallback** so they can still be matched by phone.
  </Accordion>

  <Accordion title="This lead has no syncable data">
    **What it means:** Every enabled field mapping resolved to an empty value for this lead, so there's nothing to create a contact from.

    **How to fix:** Add details to the lead (name, email, phone, …), or enable more mappings on the **Field Mapping** tab so the data the lead does have gets synced.
  </Accordion>

  <Accordion title="We couldn't sync this lead to HubSpot">
    **What it means:** Something unexpected went wrong on Caard's side — this isn't a configuration problem you can fix yourself.

    **How to fix:** Retry once. If it fails again, select **Report an issue** on the failed job — it opens a [support ticket](#still-stuck-contact-support) with the lead and the technical error details pre-filled, so our team can investigate right away.
  </Accordion>
</AccordionGroup>

## Rate limits and automatic retries

HubSpot caps how many API requests Caard can make per second. When a sync hits the cap, Caard requeues it automatically with increasing delays:

| Attempt | When it runs     |
| ------- | ---------------- |
| 1       | Immediately      |
| 2       | 30 seconds later |
| 3       | 2 minutes later  |
| 4       | 5 minutes later  |

While a retry is pending, the job shows the approximate time of the next attempt. Only after all four attempts fail is the job marked **Error** — and even then, a manual **Retry** usually succeeds once the limit has cleared.

During a large bulk sync, seeing many jobs queued and retrying is expected; they work through on their own without losing any leads.

## Company step failures

When [company sync](/integrations/hubspot#company-sync) is enabled, each job runs two steps — contact and company — and Sync History shows their results separately. If the company step fails, the outcome depends on your **On failure** setting:

* **Skip** (default) — the contact still syncs; only the company step is skipped. The job succeeds with the company failure noted.
* **Fail sync** — the entire job is marked as an error.

Company-step errors use the same error reference above — for example, a missing property on the **Company Mapping** tab produces the same "mapped field doesn't exist" error.

## List membership results

If a HubSpot list is configured, each job also records the list step:

| Result                 | Meaning                                                                                                          |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------- |
| Added                  | Contact was added to the list                                                                                    |
| Already a member       | Contact was in the list already — nothing to do                                                                  |
| Skipped (dynamic list) | The selected list is *dynamic* (membership is rule-based and read-only). Pick a **static** list on the Lists tab |
| Failed                 | HubSpot rejected the add — check the connection and list permissions, then retry                                 |

## Connection problems

If authorizing HubSpot fails and you're returned to the Integrations page with an error:

* **Wrong account or portal** — make sure you signed in to the HubSpot account and portal you intend to sync to. If your user belongs to several portals, HubSpot asks you to choose one during authorization.
* **Declined permissions** — approving only some of the requested scopes fails the connection. Restart and approve all of them.
* **Expired authorization window** — the authorization link is valid for 10 minutes. If you left the HubSpot window open longer than that, start over from the Integrations page.
* **Insufficient HubSpot permissions** — your HubSpot user needs permission to install apps. If the authorization screen shows a permissions warning, ask a HubSpot super admin to connect instead.

<Info>
  Caard's HubSpot app cannot request the notes and tasks permissions, so lead notes sync into a mapped contact property (the **Message** property by default) instead of HubSpot note records. This is expected behavior, not an error — see [how notes sync](/integrations/hubspot-field-mapping#how-notes-sync).
</Info>

## Still stuck? Contact support

If the steps above don't resolve it:

* On any failed job in **Sync History**, select **Report an issue**. This opens a new support ticket with the lead name and the full technical error pre-filled — the fastest way for our team to diagnose the problem.
* Or open the **Support** page in Caard directly and create a ticket. Include the approximate time of the failed sync and, if possible, the raw error text (hover over the error message in Sync History to see it).

You can follow the status of your ticket and reply to our team on the same Support page.