How to debug a failed sync
Open Sync History
Go to Integrations → HubSpot → Sync History. Find the job marked Error — it shows which lead failed and when.
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.
Apply the fix
Look up the error title in the error reference below and follow the fix.
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.
Error reference
These are the exact error titles you’ll see on a failed job in Sync History.HubSpot isn't connected
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.
Your HubSpot connection needs to be reconnected
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:
- Go to Integrations and select Connect on the HubSpot card.
- Sign in to the same HubSpot portal as before (the portal ID is shown on the Overview tab).
- Approve all requested permissions.
- Retry the failed jobs from Sync History.
HubSpot is missing some permissions
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.
This contact already exists in HubSpot
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.
HubSpot is rate-limiting us
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. If the job has exhausted its automatic retries, wait a minute and select Retry.
A mapped field doesn't exist in HubSpot
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:
- Open the Field Mapping tab (or Company Mapping for company errors) and find the named property.
- In HubSpot, go to Settings → Properties and check the property’s internal name — for example
lead_source_detail, not “Lead Source Detail”. - Correct the mapping, or create the property in HubSpot, or disable the mapping.
- Use Send test lead to confirm — it checks every mapped property against your live HubSpot account and flags any that don’t exist.
A field value was rejected by HubSpot
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.
This lead has no email
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.
This lead has no syncable data
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.
We couldn't sync this lead to HubSpot
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 with the lead and the technical error details pre-filled, so our team can investigate right away.
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 |
Company step failures
When 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.
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.
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.
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).