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

# Troubleshooting Integrations

> What to do when an integration asks you to reconnect, reports a missing permission, imports nothing, or fails to sync a call.

Most integration problems come down to one of four things: the connection expired, a permission
was not granted, the import scope does not match what you expected, or a CRM rejected a write.
Find the symptom below.

## "Please connect or configure your integration before dialing"

The dialer checks the integration before you start a session. This message means one of:

* **The connection is gone.** The stored session was revoked or could not be refreshed. Go to
  **Settings → Connections & API**, open the platform, and connect again. Your mappings are kept.
* **Configuration is incomplete.** Some platforms need a setting before the first call, for
  example a default call purpose in Outreach or a disposition mapping. Open the integration's
  configuration and fill in what is highlighted.

## HubSpot says a permission is missing

Messages such as "HubSpot account is missing the Companies read permission" or "missing the
Deals read permission" mean the portal did not grant one of the
[optional permissions](/integrations/hubspot#optional) when you connected. HubSpot grants
optional permissions only if the portal has the feature and the connecting user can approve
them.

Fix: disconnect HubSpot, connect again, and approve the full list on HubSpot's consent screen. If
the permission still does not appear, ask a HubSpot super admin to connect, or check that your
HubSpot subscription includes the object in question.

## The integration keeps asking me to reconnect

* **Outreach and HubSpot** issue short-lived access tokens that Salesfinity refreshes with a
  refresh token. If the refresh is rejected, the platform revoked the token. Common causes are a
  password reset with session revocation, an admin removing the app, or the user being
  deactivated in the platform. Reconnect from the settings card.
* **Salesforce** refreshes on every request. A reconnect prompt means the refresh token itself was
  revoked, usually by an admin action or an org policy that expires refresh tokens. Reconnect and,
  if it recurs, ask your Salesforce admin about the connected app's refresh token policy.

## An import returned no contacts

Check the import scope first. Importing **with no list selected** pulls your due call tasks, not
the whole CRM, and "due" is defined by the platform:

| Platform   | What "all tasks" means                                                                                                  |
| ---------- | ----------------------------------------------------------------------------------------------------------------------- |
| HubSpot    | Open tasks owned by the configured **call task source** user, due today or earlier, that are associated with a contact. |
| Salesforce | Open Tasks on the connected user, filtered by the **Task import** configuration (status, call type, due date).          |
| Outreach   | Incomplete call tasks owned by the connected user, due today or later.                                                  |

Then check these:

* **Call task source.** For HubSpot the tasks belong to the user chosen as call task source, not
  necessarily the person who connected. In a shared integration each member must be assigned one
  by the admin; until then their import is rejected.
* **Task filters.** In Salesforce, a custom task process that does not use Status and Task
  Subtype needs the Task import fields mapped, or the default filter finds nothing.
* **Empty or unreadable list.** A HubSpot list with no members, a Salesforce report that returns
  no rows, or an Outreach sequence with no prospects imports an empty list. Open it in the
  platform to confirm.
* **Field mapping.** If contacts import but show blank names or phones, the field mapping points
  at the wrong properties. Fix the mapping and re-import.
* **Invalid numbers.** Outreach imports drop phone numbers your Outreach org has flagged as
  invalid. A contact whose only number is flagged imports without a number.

## A call failed to sync

Open the call in call history. The sync state and, for failures, the reason are shown on the
call log. The reason is the message the platform returned, prefixed with the HTTP status when
there was one.

| Reason looks like                | Cause                                                                                               | Fix                                                                 |
| -------------------------------- | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
| 401 or 403                       | The connection expired or lacks a permission.                                                       | Reconnect the platform, then retry the sync.                        |
| 404                              | The record or task no longer exists in the platform.                                                | The contact was deleted or merged after import. Re-import the list. |
| 400 with a field name            | The platform rejected a mapped value, for example a disposition that is not a valid picklist value. | Fix the disposition or field mapping and retry.                     |
| 429                              | The platform is rate limiting.                                                                      | Nothing. Salesfinity waits and retries automatically.               |
| A transport error with no status | The platform did not respond.                                                                       | Retry. Salesfinity also retries these on its own.                   |

A **warning** state means the call fanned out to several CRMs and one of them failed while the
others succeeded. Only the failing CRM needs attention; retrying does not duplicate the call in
the CRMs that already have it. See [sync states](/integrations/data-flow#sync-states).

## I cannot disconnect the integration

If the message says the integration is shared with the team, you are using a teammate's shared
connection. Only its owner can disconnect it. Ask them, or have a team admin turn off sharing.

## Calls are logged as the wrong user

Calls are attributed to the platform user who connected the integration. If a manager connected
on a rep's behalf, the manager's user is the one Salesfinity acts as. Each rep should connect with
their own account. In HubSpot, the **call task source** only changes whose tasks are imported;
it does not change who calls are logged as.

## Everything looks right but the CRM is slow

HubSpot enforces a per-portal search limit shared across every app and user in the portal.
Salesforce and Outreach have their own API limits. Salesfinity throttles its requests and backs
off when a platform asks it to, so during a large import or a busy period you may see calls sit
in the queued state for longer. They will sync; nothing is lost.

## Still stuck

Email [hello@salesfinity.co](mailto:hello@salesfinity.co) with the platform, the time the problem
happened, and the sync reason from the call log if there is one. That is usually enough to find
the request in Salesfinity's logs.