CRM Sync FAQ and troubleshooting

Answers to the things that actually come up when connecting Salesforce or HubSpot. Most of them are Knowhere working as designed in a way that isn’t obvious from the screen.

Setup walkthrough: Connect your CRM. Admin steps: Prepare your CRM. Full behavior: CRM Sync.

Setup and connecting

The card says “Setup incomplete”. What’s missing?

Identity fields. Knowhere can read your CRM perfectly well and cannot write a single record to it.

Open the Verify step. It reports each object as Ready, Not created, or Not checked. On Salesforce, click Copy message for your admin and send it: it lists exactly which objects and fields are missing, pre-filled for your org. On HubSpot, a missing field means a permission wasn’t granted, so reconnect and approve the full set.

This is worth checking before you conclude anything else is broken. A connection in this state looks healthy in every other respect.

My Salesforce admin created the field but Verify still says “Not created”

Three things to check, in order:

Both checkboxes. The field needs Unique and External ID. One without the other doesn’t work.
The exact label. Knowhere External Id, giving the API name Knowhere_External_Id__c.
Field-level security. The connecting user has to be able to read and write it.

Then click Check again.

How many objects need the field on Salesforce? I’ve seen different numbers

Two: Account and Contact.

Not Event, and not ContentNote. Salesforce’s Event object can’t carry an External ID field at all, and ContentNote is file-backed and accepts no custom fields either. Knowhere correlates both a different way. Earlier guidance that said three or four objects was wrong.

Debrief notes aren’t reaching Salesforce, but everything else works

Check Notes Settings in Salesforce Setup and confirm Enable Notes is on. Debrief notes sync to the ContentNote object — Salesforce’s own dropdowns (Object Manager, a permission set’s object list) show it as Content, not ContentNote, so look for that name instead. If Notes was never turned on for your org, that object doesn’t exist in your schema, so Knowhere has nothing to write to. This won’t show as a clear error on the Verify step; it just never becomes ready.

Can I connect two CRMs, or the same CRM twice?

No. One Knowhere company holds one CRM connection. To switch, disconnect the current one first.

Should I pick Sandbox or Production for Salesforce?

Production, unless you’re deliberately testing against a Salesforce sandbox org. The choice is made at connect time and applies to the whole connection.

HubSpot has no equivalent choice; it always connects to your production portal.

What are the “recommended” fields, and should I accept them?

Nine fields Knowhere adds to your CRM: six on the company or account record, three on the contact. They hold event history as structured values, a last event name, a last event date, a meeting count, a last debrief date, a count of open follow-ups, and the outcome flagged on the latest debrief.

They’re separate from the required identity fields, and declining them still leaves you with a working sync. The full list, with names and types, is in CRM Sync.

Accept them if you want event history to end up somewhere your CRM can filter and report on. Decline them if you’d rather not add custom fields, or you want to see the sync working first.

One honest caveat: they start empty and stay empty for now. Knowhere creates the fields so the schema is ready, but populating them automatically after each debrief isn’t live yet. Accepting the tier today is about getting the setup out of the way, not about a report you can run this week.

Why do the reporting fields have specific types?

Because a date stored as Text can’t go in a date filter and a count stored as Text can’t be summed. Getting the type wrong produces a field that looks right and can’t be reported on, which is the one thing these fields exist to fix.

On HubSpot this is handled for you. On Salesforce your admin picks the type by hand, so the type column in Prepare your CRM is the part not to improvise.

A reporting field is empty. Is it broken?

Probably not, see above: automatic population isn’t live yet, so empty is currently expected.

Worth knowing regardless: there’s no verification step for these the way there is for identity fields. The Verify screen checks identity only. If one is missing or misspelled, nothing tells you.

The mapping grid is empty right after I connect

Knowhere reads your CRM’s schema in the background as the connection completes, and on a large org that takes a moment. Refresh the page.

If it’s still empty, the connecting user probably lacks permission to describe those objects.

”Why isn’t this syncing?”

My meeting isn’t in the CRM

Meetings sync after they’ve happened. Knowhere pushes a meeting once it has ended and it isn’t cancelled. This is deliberate: the CRM should reflect meetings that took place, not a calendar of intentions.

So a meeting won’t push if:

It’s still in the future. Wait until after its end time.
It’s cancelled.
It’s an imported meeting that came in from a forwarded email invite. Those never sync, in either direction, because they’d duplicate what your calendar already put in the CRM.

My meeting notes aren’t in the CRM

Only a filed debrief syncs. Raw notes typed on a meeting stay in Knowhere.

Complete the structured debrief and it becomes a note on the matching CRM record. Editing that debrief later updates the same note rather than creating a second one. See Add notes and generate a Debrief.

Why can’t I see the contacts that synced from my CRM?

They’re there. They’re hidden until they’ve actually been in a meeting.

A contact pulled in from your CRM stays out of the All Contacts page and the organization’s “People from this company” list until they’re an attendee on a meeting (or you archive them, so archived contacts stay findable to restore). Without that rule, importing an account brings in its entire contact list and buries the handful of people your team is actually meeting.

Add the contact to a meeting and they appear in both lists immediately.

A deal isn’t showing on the organization

Two likely reasons:

The account isn’t linked. Deals only come across for accounts Knowhere has synced. A deal on an account outside your sync scope is correctly absent.
The deal is closed. Closed deals drop off the open list by design.

Deals are read-only in every direction. Knowhere shows your pipeline and never writes to it.

The Pipeline section on an event doesn’t match what I expected

Two behaviors that are deliberate, not bugs:

It counts met accounts and the event’s target accounts, not your whole CRM. An account only shows up here if your team met it at this event, or it’s on this event’s target list, whether anyone met it or not. That second half is also why an unmet target’s pipeline can show up in the Uncovered tile even though nobody talked to them.
Multi-currency totals are summed as raw numbers, with no conversion. If your deals are in more than one currency, treat the totals as directional rather than exact. There’s currently no FX conversion, so a mixed-currency total isn’t a real dollar figure.

See CRM Sync for what each widget shows.

The account owner is blank

Knowhere matches your CRM’s account owner to a Knowhere team member by email address, exactly (case doesn’t matter, anything else does). A rep whose CRM login email differs from their Knowhere email won’t match.

Fix the mismatch on either side, then run Sync now.

I changed something in the CRM. How long until Knowhere has it?

Record changes come across within a few minutes. Deals and CRM activity refresh less often.

If you don’t want to wait, click Sync now on the CRM Sync card. It runs all three jobs immediately and tells you how each one did, separately, because “deals didn’t pull” and “nothing sent” are different problems.

Mapping

Can I make a field sync only one way?

Direction isn’t set per field. It follows who owns the record:

Your CRM owns companies and contacts, so those flow in.
Knowhere owns meetings and debriefs, so those flow out.

That’s a deliberate product decision, not a missing setting. “Both sides can edit it” is last-write-wins with a friendlier name, and it produces exactly the silent overwrites this rule avoids.

The one exception: an organization or contact you create in Knowhere has no CRM record yet, so the first push carries what you typed. From the second push onward your CRM’s values stand.

Knowhere won’t let me leave the Mapping step

Your CRM requires a field that nothing is mapped to. The Required tab collects every such field across all record types, each with its own note about what’s unsatisfied.

This is the check that stops you discovering the problem later, one failed record at a time. A common case is a CRM that requires Country on every contact.

Both Domain and Website suggest “Website”

Known rough edge. Knowhere’s auto-match offers your CRM’s Website field for both, and only one of them will bind, so on HubSpot the Domain mapping can end up empty.

Set the mapping you want by hand on the Accounts or Companies tab. It saves automatically.

A field I need doesn’t exist in my CRM yet

Create it in your CRM first, then reconnect so Knowhere re-reads the schema. It’ll be in the picker.

You can’t create a new CRM property from inside the mapping step.

I mapped a field but it isn’t being written

Check, in order:

The mapping is enabled. Only enabled mappings sync.
Direction allows it. A field on a CRM-owned record (company, contact) flows in, not out.
It isn’t free text. Notes and descriptions are held back from outbound writes by default.
The connecting user can write it. A field that’s read-only for that user is silently unwritable.

Errors and recovery

The card says “N records failed”

Click through to the list. Each entry carries the reason your CRM gave.

Failures retry automatically on a widening schedule (about a minute, then five, then thirty, then two hours, then twelve) and stop after five attempts. Fixing the underlying cause and clicking Sync now is faster than waiting for the next retry.

The most common causes are a required CRM field nothing is mapped to, a field the connecting user can’t write, and a permission that was revoked after connecting.

The connection says it needs reconnecting

Knowhere refreshes its own credentials in the background, so this normally means access was revoked or changed on the CRM side. Click Reconnect and re-authorize.

What happens when I disconnect?

The connection closes and stored credentials are cleared.
Anything still queued to send is dropped.
Editing an organization in Knowhere after that queues nothing.
Records that already synced stay put, on both sides. Nothing is deleted.

If I reconnect, will everything import twice?

No. Reconnecting to the same CRM picks up the existing links, so records are matched rather than re-created.

Reconnecting to a different CRM is a clean slate: suggestions from the old one won’t appear.

Things to expect

Current behavior worth knowing about before it surprises you.

Accounts outside my sync scope are appearing

Sync scope shapes the first import. Ongoing pulls aren’t re-filtered against it, so an account outside your original scope can arrive later if it’s changed on the CRM side.

If the scope was meant to keep your Knowhere workspace tight, keep an eye on the organization list and expect to prune it.

There’s no list of everything that synced

Synced accounts don’t have a browser of their own yet. You meet them where you need them: start typing in a meeting’s organization picker and CRM accounts appear, badged Salesforce or HubSpot, with Not synced on the ones that exist in your CRM but aren’t in Knowhere yet. Picking one creates it for real, on the spot, and doing it twice gives you one organization rather than two.

The lightweight directory can go stale

The searchable index of your CRM accounts is built during the first import and isn’t refreshed on every subsequent pull. An account created in your CRM well after setup may not appear as a suggestion. Reconnecting rebuilds it.

I created an organization in Knowhere and got a duplicate in my CRM

Knowhere creates a new CRM record for an organization that originated in Knowhere, even when a record with the same domain already exists there. It matches on its own identity field, not on domain.

If the account already exists in your CRM, the cleaner path is to find it in the picker (it’ll show as Not synced) and let Knowhere link the two, rather than typing a new organization by hand.