Skip to content

ClientVerse Troubleshooting Guide

This guide is for the people who keep a ClientVerse org running: the CRM administrator, the support team fielding "it's broken" tickets, and the implementation consultant during and after a deployment. It is organized by symptom — jump to what the user is seeing and work back to the cause.

Audience-first. Users learning a feature start with the User Guide; people configuring the product use the Admin Guide and Configuration Reference (this guide points back to them). Troubleshooting assumes the product is installed and you are diagnosing a failure.

Default assumption: your org has Core only. Sections requiring the optional Modules add-on (Dispatch, Whitespace) carry a 🧩 badge. Without Modules, those objects, apps, and tabs won't exist — a "missing object" there is expected, not a bug.

All package facts here (object/app names, permission sets, versions, counts) are cited from the synced _package-facts/, never from memory.

1. How to use this guide

Every entry uses the same three-line shape — Symptom (what's observed) → Likely cause (the most common root cause; start here) → Resolution (the step, or a pointer to the guide that owns the fix). Work top-down within a section; earlier entries are the more common causes. When an entry points at another guide, that guide owns the procedure — this one only tells you which knob to look at.

Gather diagnostics first

Before escalating, collect these. Most ClientVerse issues are diagnosable from them.

  • Clientverse_Log__c — the Core logging object. ClientVerse writes operational and error log rows here (and 🧩 Dispatch extends it with Action__c / Run_Item__c lookups so digest activity is visible in the same place — see dispatch.yaml). Filter by created date and by the feature you're chasing; the most recent error rows usually name the failing component. Confirm the support user has read access to it (see Permission problems).
  • Salesforce debug logs — for an Apex / flow / batch failure, add a trace flag on the running user (the Automated Process user for scheduled jobs, the integration user for syncs) in Setup → Debug Logs, reproduce, and read the stack. ClientVerse Core ships 17 triggers and 288 Apex classes and Modules adds 74 more (see clientverse-core-1.1.7.json, clientverse-modules-0.4.0.json) — the debug log tells you which one threw.
  • Setup Audit Trail — for "it worked yesterday" problems, check who changed a permission set, validation rule, or scheduled job recently.
  • Package versions — from Setup → Installed Packages, record the installed ClientVerse Core and ClientVerse Modules versions. Many issues below turn on the exact version (especially the Core ↔ Modules compatibility gate in Install & upgrade).

When you open a ticket or escalation, attach the relevant Clientverse_Log__c rows, the debug log, and the two package versions. See Escalation.

2. Install & upgrade issues

ClientVerse Core is an unlocked package (namespace clientverse); ClientVerse Modules is a managed package on top of Core. Install/upgrade problems almost always come down to order and version compatibility. The full procedure lives in the Implementation Guide; this section is for diagnosing a failed or blocked install, not the happy path.

Modules 0.4.0 requires Core 1.1.7 — installing on an older Core fails the dependency check

  • Symptom: installing ClientVerse Modules 0.4.0 into an org running Core older than 1.1.7 fails with a missing-dependency / required-package-version error, naming a ClientVerse Core version the org doesn't have.
  • Likely cause: Modules 0.4.0 declares a dependency on ClientVerse Core Unlocked@1.1.7-6 (package version id 04tfj000000TYCnAAO). An org below that baseline is missing the required Core version, so the platform blocks the Modules install until Core is upgraded. See clientverse-modules-0.4.0.json (the depends_on block) and sync-report.md.
  • Resolution: upgrade Core to 1.1.7 first, then install Modules 0.4.0. This is the single most common Modules install blocker. Do not attempt to force the install past the dependency check.

This catches orgs that were previously fine. Modules 0.3.0 required only Core 1.1.4, so an org happily running 0.3.0 on Core 1.1.4, 1.1.5 or 1.1.6 is below the 0.4.0 floor. A working Modules org is not evidence that it is ready to upgrade Modules — check the installed Core version explicitly.

Package installed in the wrong order (Modules before Core)

  • Symptom: Modules install fails immediately, or installs but its objects/Apex reference Core objects that "don't exist."
  • Likely cause: Modules is a managed add-on on top of Core. Core must be present (and at the required version, above) before Modules.
  • Resolution: install Core first, Modules second. If Modules was somehow installed first and is in a broken state, uninstall it, confirm Core is at the required version, and reinstall Modules.

Install fails on a dependency or component conflict

  • Symptom: the package install job fails partway with a component or dependency error (e.g. a metadata component already exists, or a referenced object is missing).
  • Likely cause: a prior partial install, a hand-modified component colliding with the packaged one, or an org that doesn't meet a feature prerequisite.
  • Resolution: read the install failure detail (it names the component), resolve the named collision, and retry. Always install into a sandbox first and promote — never debug a failed install directly in production. The Implementation and Deployment docs own the sandbox-first procedure.

"I can't find the clientverse objects/fields after install" (namespace confusion)

  • Symptom: after install, admins look for objects like Account extensions or custom objects and either can't find them or see API names prefixed unexpectedly.
  • Likely cause: namespace confusion. Both packages use the namespace clientverse (see the two package JSONs). Core is unlocked, so in many orgs its components appear without a managed namespace prefix on the API name; Modules is managed. Admins searching for the wrong prefix conclude the component is missing.
  • Resolution: confirm the component is really absent before treating it as a bug. Search Object Manager by label as well as API name, and cross-check the object list in clientverse-core-1.1.7.json (148 Core objects) and clientverse-modules-0.4.0.json (21 Modules objects). If the object is on the Modules list and the org has Core only, it is correctly absent.

Upgrade ran but new fields/objects aren't visible to users

  • Symptom: the package upgrade succeeded, but users still don't see new fields, tabs, or objects.
  • Likely cause: new components ship without field-level security or tab visibility for existing users — those are granted by permission sets, which an upgrade does not re-assign.
  • Resolution: after any upgrade, re-check permission-set assignments against the new release. See Permission problems and the Admin Guide.

3. Permission problems

Almost every "I can't see X" in ClientVerse is a permission-set or permission-set-group assignment problem, not a data problem. Core ships 24 permission sets and 6 permission-set groups; Modules adds 3 permission sets (see the package JSONs). The Admin Guide owns the full access model and the permission-set → app map; this section is the fast symptom lookup. The recurring trap throughout: object access and field-level security are granted by permission set, not profile — so what one user sees, another (or an integration user) may not.

"I can't see the app" (app launcher is missing a ClientVerse app)

  • Symptom: a user can't find CV_BD, CV_Lawyer, CV_Marketing, CV_Intelligence, CV_Experience, or CV_Admin in the App Launcher (Core ships 6 apps), or 🧩 CV_Dispatch_Setup (the one Modules app).
  • Likely cause: the user lacks the permission set / permission-set group that grants the app, or (for the Modules app) the org doesn't have Modules.
  • Resolution: assign the appropriate permission-set group from the Admin Guide's access map. Confirm the app name against clientverse-core-1.1.7.json / clientverse-modules-0.4.0.json before concluding it's missing.

"I can't see a tab"

  • Symptom: an object's tab is absent from an app's navigation for one user.
  • Likely cause: tab visibility is granted by permission set; the user is missing it, or has it set to hidden on their profile and no permission set overrides it.
  • Resolution: grant the permission set that exposes the tab. Core defines 52 tabs, Modules 9 — if the tab is a Modules tab and the org is Core-only, it is correctly absent.

"I can't see an object / I get 'insufficient privileges'"

  • Symptom: opening a record or list view returns insufficient privileges, or the object doesn't appear in Object Manager for that user.
  • Likely cause: object-level CRUD is missing. ClientVerse grants object access through data-access permission sets (e.g. CV_Relationship_Data_Access, CV_Financial_Data_Access) rather than profiles.
  • Resolution: assign the data-access permission set that covers the object. For merge operations specifically, the user needs CV_Merge_Records; for bulk import, CV_Data_Import_Full_Access (see Data & import).

"I can see the record but a field is blank / read-only / missing"

  • Symptom: a field the user expects is not on the page, is greyed out, or is empty even though data exists.
  • Likely cause: field-level security (FLS) is permission-set-granted in ClientVerse. A user (or an integration user) without the granting permission set sees the field as hidden or read-only — even if another user can see it. This is a known trap: don't assume a field is accessible to one user just because another user has it (see ../../GOTCHAS.md).
  • Resolution: grant the permission set that includes that field's FLS. For integration/import failures caused by this, both the importing user and the integration user need their permission sets — see Integration issues.

"They can see the records but not the buttons" — Schema Access without User

  • Symptom: after 1.1.7, a user can open an object's records and see its fields, but the ClientVerse components, buttons or actions in that area do nothing or aren't rendered.
  • Likely cause: they hold only the area's *_Schema_Access set. That tier grants object, field, record-type and tab visibility and deliberately grants no Apex or LWC access — it exists so reporting and integration users can see data without holding code access.
  • Resolution: assign the matching *_User set alongside it (e.g. CV_BD_User in addition to CV_BD_Schema_Access), and confirm CV_Base_Access is assigned. This is the most common new access ticket after the 1.1.7 restructure — see Admin Guide §4.1.

A permission-set group seems to grant nothing

  • Symptom: assigning a permission-set group doesn't give the expected access.
  • Likely cause: the user was assigned a different group than intended, or the group's muting/permission-set membership differs from expectation.
  • Resolution: verify against the 8 permission-set groups listed in clientverse-core-1.1.7.json and the Admin Guide's mapping. Confirm the user holds the intended group (for executives, the canonical group is CV_Executive). CV_Admin_Team and CV_Lawyer_Team are new in 1.1.7 — an org upgraded from 1.1.6 will not have anyone assigned to them yet.

4. Data & import issues

Import and data-entry failures in ClientVerse usually trace to a required field, a record type, a validation rule, or duplicate handling. The Migrations docs own bulk-load procedure and the Data Model / Data Dictionary owns field-level requirements — cite those for specifics; the entries here are for diagnosing the failure.

Import rejects rows for a missing required field

  • Symptom: a load (Data Loader, import wizard, integration) fails rows with a required field missing error.
  • Likely cause: a required field — or a required-on-record-type field — isn't in the load file or is blank.
  • Resolution: check the object's required fields in the Data Dictionary and add them to the mapping. For administrative system fields like Production_ID__c, follow the migration mapping rather than inventing values.

"Records load but land with the wrong layout / picklists are wrong" (record type)

  • Symptom: imported records open on an unexpected page layout, or picklist values the user expects are missing.
  • Likely cause: record type wasn't set on import (Core defines 34 record types — see clientverse-core-1.1.7.json), so records fell to the default record type, or the importing user's profile/permission set doesn't have the intended record type assigned.
  • Resolution: map the RecordTypeId (or developer name) explicitly in the load, and confirm the importing user has access to that record type.

Import fails on a validation rule

  • Symptom: rows are rejected with a custom error message from a validation rule.
  • Likely cause: the data legitimately violates a rule, or a rule that should be bypassed for migration is firing on the load.
  • Resolution: read the error — it's the validation rule's own message. Fix the data, or, for a controlled bulk migration, follow the migration runbook's guidance on a migration context (e.g. the CV_Data_Migration permission set and any documented bypass). Don't disable validation rules ad hoc in production.

Duplicate records / merge not behaving

  • Symptom: imports create duplicates, or a user can't merge two records.
  • Likely cause: duplicate rules / matching didn't catch the inbound records, or the user lacks merge permission.
  • Resolution: for merge access, assign CV_Merge_Records. There is also an Override_Auto_Generated_Name permission set for cases where the auto-named record needs a manual name on merge/create — see clientverse-core-1.1.7.json and the Admin Guide. For the matching logic itself, see the Data Model and Migrations docs.

Rollup numbers look wrong after a load

  • Symptom: summary/rollup fields don't match the underlying records after a bulk import.
  • Likely cause: rollups recalculate on DML; a bulk load may have bypassed them or they haven't finished.
  • Resolution: an admin with CV_Rollups_Admin can trigger/recalculate rollups. See the Admin Guide for the rollup administration procedure.

5. Integration issues

ClientVerse integrates with external PMS (3E, Aderant), ERM (Introhive, SigParser), and MAP (Pardot / MCAE) systems, plus HR/AD, Vuture, and web forms. The Integrations docs are the source of truth — start at 00_Integration_Architecture.md. This section covers the failures that surface in ClientVerse.

A sync stops bringing in records (PMS / ERM / MAP)

  • Symptom: financial data, relationship/activity data, or marketing engagement stops updating; records go stale.
  • Likely cause: the integration user's credentials expired, the scheduled sync job failed, or upstream the external system stopped sending.
  • Resolution: check Clientverse_Log__c for sync error rows and the scheduled-job status, then the relevant per-system spec (PMS, ERM, MAP).

Sync runs but specific fields never populate

  • Symptom: records sync, but certain fields stay empty even though the source has them.
  • Likely cause: the integration user lacks field-level security on those fields. This is the canonical trap — FLS is permission-set-granted, so a field visible to a human admin can still be invisible to the integration user (see ../../GOTCHAS.md).
  • Resolution: assign the integration user the permission set(s) that grant FLS on the affected fields. Both the importing user and the integration user need their permission sets.

Marketing send / engagement data out of sync (MAP)

  • Symptom: Pardot / MCAE sends or engagement scores don't reflect in ClientVerse, or vice versa.
  • Likely cause: the MAP connector sync is paused, mapping is misconfigured, or a send is going through the external MAP path (relevant to 🧩 Dispatch's Use_External_MAP__c option below).
  • Resolution: see Integration_Marketing_Pardot_MCAE.md. If the affected sends originate from Dispatch with external MAP enabled, also see Dispatch issues.

6. 🧩 Dispatch issues

🧩 ClientVerse Modules — Dispatch Requires the ClientVerse Modules package. Clients on Core only won't see this.

Dispatch is the data-driven notification/digest engine: an admin defines a Dispatch_Definition__c (audience, content query, schedule, channel); a scheduled Dispatch_Run__c evaluates it, creates one Dispatch_Run_Item__c per recipient, renders, and delivers. Object/field meaning is in dispatch.yaml; configuration procedure is in the Configuration Reference and Admin Guide.

Digests aren't sending at all

  • Symptom: a scheduled digest never goes out; no Dispatch_Run__c records appear at the expected time.
  • Likely cause (start here): the definition is inactive — Dispatch_Definition__c.Active__c is false, so the scheduler skips it.
  • Resolution: confirm Active__c is checked on the Dispatch_Definition__c. Then verify the schedule fields: Frequency__c, Run_Times__c, and for weekly/monthly cadence Day_of_Week__c / Day_of_Month__c, plus Timezone__c (the schedule is evaluated in that timezone — a wrong timezone makes a digest look "missed"). See dispatch.yaml.

A run executed but nothing was delivered

  • Symptom: a Dispatch_Run__c exists but Items_Sent__c is 0 (or much lower than expected) and there are failures.
  • Likely cause: delivery failed — read the run's roll-up counters and error text.
  • Resolution: open the Dispatch_Run__c and read Records_Evaluated__c, Items_Created__c, Items_Sent__c, Items_Failed__c, and especially Error_Summary__c (the aggregated error detail for the run). Drill into individual Dispatch_Run_Item__c rows for per-recipient Status__c. Cross-reference Clientverse_Log__c for the same window.

Items are skipped

  • Symptom: fewer recipients got the digest than expected; some run items show as skipped.
  • Likely cause: per-item suppression — the Dispatch_Run_Item__c.Skip_Reason__c field records why (e.g. unsubscribed, no email, throttled, empty content).
  • Resolution: read Skip_Reason__c on the skipped Dispatch_Run_Item__c rows. Common causes: the subscriber opted out (Dispatch_Subscription__c.Unsubscribed_Date__c set or Is_Active__c false), the recipient has no deliverable address, or a section was empty and suppressed by Dispatch_Section__c.Hide_If_Empty__c.

Sending stops mid-run — daily contact-email limit hit

  • Symptom: a run starts delivering, then the remaining items are skipped/deferred with a throttle-related skip reason; recurs at roughly the same volume each day.
  • Likely cause: the daily contact-email limit guardrail. Dispatch_Settings__c holds org-level throttling counters (and the last reset date) that cap how many contact emails Dispatch sends per day; once the counter is exhausted, further sends are held.
  • Resolution: check Dispatch_Settings__c for the current daily counter and reset date (see dispatch.yaml). If you are legitimately hitting the cap, stagger schedules across days or raise the limit per the Admin Guide — and remember Salesforce's own org-wide single-day email limits sit underneath this guardrail.

Replies aren't routing back into Salesforce

  • Symptom: recipients reply to a digest but the replies never appear in ClientVerse.
  • Likely cause: reply routing isn't enabled or addressed correctly on the definition.
  • Resolution: confirm Dispatch_Definition__c.Enable_Reply_Routing__c is on and that Reply_To__c (and From_Address__c / From_Name__c) are set to addresses the routing flow can receive. Reply routing depends on the inbound flow being active — check it ran in the debug log and that the inbound address is configured. See dispatch.yaml.

Per-recipient content is wrong or empty

  • Symptom: the digest body is missing sections or shows the wrong rows for a recipient.
  • Likely cause: section visibility / context configuration — Dispatch_Section__c.Visibility_Rule__c, the data-table source (Dispatch_DataTable_Config__c), or the definition's Context_Mode__c (per-recipient vs shared context).
  • Resolution: verify the section's Visibility_Rule__c and Hide_If_Empty__c, the data table's Data_Source_Type__c / SOQL_Template__c, and the definition's Context_Mode__c. The Configuration Reference owns digest authoring.

7. 🧩 Whitespace issues

🧩 ClientVerse Modules — Whitespace Requires the ClientVerse Modules package. Clients on Core only won't see this.

Whitespace scores account/practice-area coverage gaps via a batch and surfaces the top opportunities as WhiteSpace_Opportunity__c records (and an optional digest). Scoring is driven by custom metadata: Whitespace_Scoring_Config__mdt, Whitespace_Score_Weight__mdt, and Whitespace_Threshold__mdt. Cite whitespace.yaml for meaning.

No opportunities are generated

  • Symptom: the Whitespace dashboard/digest is empty; no WhiteSpace_Opportunity__c records are being created.
  • Likely cause (start here): scoring is disabled — Whitespace_Scoring_Config__mdt.Active__c is false, so the batch doesn't run.
  • Resolution: confirm Active__c on Whitespace_Scoring_Config__mdt. Then verify the batch actually executed (check the scheduled/Apex batch job status and Clientverse_Log__c) and that Batch_Size__c and the candidate population are sane. If the batch ran but produced nothing, the thresholds may be excluding everything — see the next entry.

Scores look wrong or rank unexpectedly

  • Symptom: opportunities appear, but the scores or ordering don't match expectations — high-value gaps rank low, or everything clusters at one value.
  • Likely cause: scoring weights or thresholds are misconfigured. The composite Opportunity_Score__c is the weighted sum of the component scores (Score_Client_Tier__c, Score_Peer_Coverage__c, Score_Relationship_Strength__c, Score_Revenue_Potential__c), each capped by a Whitespace_Score_Weight__mdt row; and Coverage_Status__c is driven by Whitespace_Threshold__mdt hour thresholds.
  • Resolution: review the per-factor Whitespace_Score_Weight__mdt rows (Factor_Name__c, Max_Points__c, Active__c — a deactivated factor drops out of the composite) and the Whitespace_Threshold__mdt rows (Active_Hours_Threshold__c, Partial_Hours_Threshold__c per practice). After changing weights/thresholds, re-run scoring so existing records re-compute. See whitespace.yaml and the Configuration Reference.

Opportunities generate but the digest doesn't send

  • Symptom: WhiteSpace_Opportunity__c records exist, but no opportunity digest email goes out.
  • Likely cause: the digest is disabled or scheduled for a different time — Whitespace_Scoring_Config__mdt.Send_Digest__c, Digest_Day_Of_Week__c, Digest_Hour__c.
  • Resolution: confirm Send_Digest__c is on and the day/hour are correct, and that Top_Opportunity_Count__c is greater than zero. See whitespace.yaml.

8. Known issues & limitations

These are current, expected constraints — not bugs to chase. They come from the synced package facts; see the Flags in sync-report.md.

Modules 0.4.0 requires Core 1.1.7

  • What: Modules 0.4.0 declares a dependency on ClientVerse Core Unlocked@1.1.7-6. An org on any earlier Core cannot install Modules 0.4.0 until Core is upgraded. The floor moved up from 1.1.4 in this release.
  • Impact: plan a Core upgrade before any Modules rollout on an org below 1.1.7 — including orgs already running Modules 0.3.0 successfully. Full detail in Install & upgrade.

"Where is AI Chat / the Power BI component?" — shipped in 0.4.0, off by default

  • Symptom: someone with Modules 0.4.0 looks for the CV AI Chat tab or a Power BI / Tableau component and can't find it. Or the reverse: someone was told AI "isn't available" and wants to know when it lands.
  • What: both AI and Analytics ship in Modules 0.4.0. This changed in this release — through 0.3.0, analytics was genuinely absent and ai was configuration metadata only, and older documentation says so. They are now present but gated: nothing is visible to any user until the permission set is assigned.
  • Resolution: assign the relevant permission set — CV_AI_Chat_User for the chat, CV_BI_Visualization for BI embedding (both require CV_Modules_Access first). If the org is on Modules 0.3.0 or earlier, the components genuinely are absent and a Modules upgrade is required — which also means a Core upgrade to 1.1.7 first.
  • Before enabling AI, note two things: queries run in USER_MODE so record access is enforced, but CRM data is sent to Anthropic or OpenAI, and prompt-injection hardening is incomplete. That is a firm-policy decision, not a support action — route it to whoever owns the firm's AI position rather than assigning the set on request. See the Admin Guide §14.

Low metadata annotation coverage

  • What: object descriptions are now largely in place (Core 92%, Modules 90%), but most fields still ship without a description or inline help (Core 36% of fields described, Modules 11%; inline help 4% on both — see sync-report.md). Users won't find on-field help text for most fields.
  • Resolution: this is expected and tracked for backfill. Point users at the Data Dictionary and the annotation catalogs (objects/*.yaml) for field meaning rather than relying on in-app help.

9. Escalation / where to get help

Resolve what you can with the diagnostics in §1, then escalate with that evidence attached.

  1. Confirm it's not configuration. Re-check the relevant section above — permission-set assignment, an Active__c flag, a schedule field, or a thresholds/weights value resolves the large majority of tickets without code involvement.
  2. Gather the diagnostic bundle. Clientverse_Log__c rows for the window, the Salesforce debug log for the failing user/job, the Setup Audit Trail entry if something changed, and both installed package versions (Core and Modules). See §1.
  3. Route by area:
  4. Access / data / day-to-day admin → the Admin Guide.
  5. Configuration of a feature (Dispatch digests, Whitespace scoring) → the Configuration Reference.
  6. Install / upgrade / environment → the Implementation Guide and Deployment docs.
  7. External sync failures → the relevant Integration spec.
  8. A confirmed package defect → escalate to the product/engineering owner with the diagnostic bundle and the exact Core/Modules versions from _package-facts/.
  9. Stay customer-neutral and NDA-safe. When filing an escalation outside the firm, keep customer names and firm-specific data out of the ticket per the documentation conventions (../_conventions.md).

Unresolved facts

  • Dispatch reply-routing inbound setup. The exact inbound-email/flow configuration that backs Enable_Reply_Routing__c is described at the field level only; the operational setup procedure should be cross-linked once the Configuration Reference documents it.
  • Daily contact-email limit value. Dispatch_Settings__c enforces a daily contact-email cap, but the default/configured limit value and how to change it are owned by the Admin Guide and not fixed in the package facts.