> For the complete documentation index, see [llms.txt](https://docs.ebbot.ai/ebbot-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ebbot.ai/ebbot-docs/integrations/automations-integrations/integration-setup-guides/hubspot-integration-in-automations/troubleshooting.md).

# Troubleshoot the HubSpot integration

Start with the ticket/object ID, workflow and run, timestamp with timezone, expected result and first node whose actual output differs. The run trace and destination record are more useful than the final generic error alone.

## Find the failing layer

| Symptom                                           | Check                                                                             | Interpretation                                                                                  |
| ------------------------------------------------- | --------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| Connection validation fails                       | Access token, base URL and ticket-read permission                                 | Validation reads tickets; it does not test all other capabilities                               |
| No run starts                                     | Matching app/connection, active subscription, exact callback, real event delivery | Creating the trigger does not configure HubSpot for you                                         |
| Webhook 401                                       | Client secret, signature/timestamp headers and public URL                         | For a correct connection, Ebbot may need to inspect proxy URL reconstruction or clock alignment |
| Webhook callback 404                              | Installed trigger exists and app targets its current URL                          | Do not assume every workflow publish rotates the callback                                       |
| Batch acknowledged but expected run absent        | Event-type filter and per-event dispatch evidence                                 | A successful batch response is not proof every event dispatched or completed                    |
| Many runs per ticket                              | `property_name`, `change_source`, owner/state and stop conditions                 | No-action runs may be correct; repeated side effects are the problem                            |
| Real reply ignored                                | Watched property actually changed; source and owner pass                          | A property-change trigger is not a universal new-message trigger                                |
| Transcript empty                                  | Thread presence, CRM Note association, Include Notes and write timing             | Include Internal Comments does not fetch CRM Notes                                              |
| History incomplete                                | Thread selection and page limits                                                  | Get Ticket and association helpers do not traverse all historical pages                         |
| Internal answer irrelevant                        | Actual retrieval query, selected dataset and returned sources                     | Correct raw data elsewhere in a node is not enough if the wrong field feeds retrieval           |
| Public reply reports success but no email arrives | Conversation path versus Email engagement fallback                                | Logging a CRM Email engagement does not deliver an email                                        |
| Public send 403                                   | Sending actor, channel access and app scopes                                      | CRM owner and Conversations sender are different identities                                     |
| Wrong owner/status                                | Owner ID versus user/actor ID; stage in correct pipeline                          | Display labels and numeric values are portal-specific                                           |
| `success: false, exists: true` on custom update   | Payload, permitted values and returned-property comparison                        | It can mean a 400 or a response mismatch; some writes may already have occurred                 |
| Search/list misses records                        | Paging support and requested properties                                           | Several convenience actions fetch only one page                                                 |
| A linked object section is missing                | Per-association request failure as well as actual relationships                   | Get Object Associations can return the primary record after skipping a failed association read  |
| HTML looks wrong                                  | Generated content, stored body and rendered UI                                    | Markdown is not the supported formatting contract for these send/note inputs                    |

## Missing data and output flags

Many read actions return `exists: false` for no result rather than raising an error. The precise meaning differs: an absent record, no matching records or no returned definitions. Check the individual action page.

Write actions can return false flags after a create/association failure. Conversely, a successful write output need not mean the customer-facing outcome has completed. Check the destination and which branch the action used.

Property models include nullable/default fields. A declared `phone`, `owner` or body field is not proof that the API returned it. Use the appropriate all-fields option or explicit property request.

## Requests, rate limits and retries

The documented HubSpot HTTP helper uses a 10-second request timeout and up to **three total attempts** for connection errors, timeouts and HTTP 429, 500, 502, 503 or 504. Backoff begins at two seconds. Other ordinary 4xx responses are not retried by that helper; 404 is passed back as a missing-resource result for the action to interpret.

This is connector-request retry behavior. It is **not** an automatic retry guarantee for an LLM's invalid structured JSON, an entire failed workflow, webhook dispatch or a Note that has not been created yet.

Read/write retries do not establish exactly-once side effects. A timeout can leave uncertainty about whether a write succeeded. Before manually replaying a run, inspect completed actions and the destination to avoid duplicate replies, Notes or state changes.

HubSpot API limits depend on the account and operation. Consult [HubSpot's current usage guidance](https://developers.hubspot.com/docs/api/usage-details) rather than hardcoding an account limit into the workflow.

## What to send to Ebbot Support

Provide the integration/action or trigger name, run link, affected record ID, timestamp/timezone, expected versus actual behavior, relevant node inputs/outputs and the underlying HTTP/error message when available. Include only the customer content needed to reproduce the problem; omit access tokens, client secrets and complete signed resolution links.

For server-side investigation, Ebbot can correlate the workflow run with connector logs. If a chat Extension created the data, that component has a separate execution path from this Workflow Server. Distinguish a creation problem from a retrieval problem before changing the flow.

## After a fix

Repeat the smallest test that demonstrates the intended outcome and the adjacent boundary that could regress. Record whether the change was configured, published and observed in the destination. Update the customer solution guide with the reason for the change and the verified result.