Troubleshooting

This page lists the PRIMA CRM problems that the product’s own code and release notes describe, grouped by where you meet them. Each entry gives what you see, why it happens and what to do. Error messages appear as Claude reports them, and Claude may show them inside a longer reply.

Starting the Server

The Server Stops at Once

Symptom. /mcp lists prima-crm as failed, or the CRM tools are missing. The server log shows ⚠ PRIMA CRM needs the AI Business OS project register. followed by one of three reasons.

Reason	What it means
state.json not found at <path>. Install AI Business OS and run /setup first, from the workspace root.	The folder the server started in has no .claude/state/state.json
state.json exists but does not contain a valid projects array. Run /setup in AI Business OS to rebuild it.	The register is there but has no projects list
state.json exists but could not be parsed. Check the file for syntax errors.	The register is not valid JSON

Cause. PRIMA CRM reads the AI Business OS project register to connect companies to projects, and it will not start without one.

Fix. If the file is missing, check that you opened Claude Code from your workspace root (see the next entry). If you have not set up AI Business OS yet, follow Running Setup. If the file is damaged, ask Claude to run Scripts/validate-state.sh and show you what it reports, or restore the file from a backup copy. Then restart Claude Code.

The CRM Is Empty or Shows the Wrong Records

Symptom. Companies you added yesterday are missing, or a .prima-crm/ folder has appeared in a folder you did not expect.

Cause. The server takes its workspace from the folder where you started Claude Code, not from the folder that holds the server code. If that folder has its own .claude/state/state.json, the server creates a separate .prima-crm/ database there and works from it.

Fix. Close Claude Code and open it again from your workspace root. Your records are still in .prima-crm/crm.db in that folder. Move or remove the stray .prima-crm/ folder only after you have checked that it holds nothing you need.

The Server Fails After a Node.js Upgrade

Symptom. The CRM worked, you upgraded Node.js, and now the server fails to start.

Cause. PRIMA CRM stores its data with better-sqlite3, a module that the install compiles for the Node.js version you had at the time.

Fix. Ask Claude to run npm rebuild in .claude/mcp-servers/prima-crm/, or npm install if the rebuild does not help, then restart Claude Code.

Data and Settings

A Copy of the Database Is Missing Recent Changes

Symptom. You copied crm.db to another computer or a backup, and the copy lacks your latest records.

Cause. The database runs in WAL mode. Recent writes sit in crm.db-wal until SQLite folds them into crm.db.

Fix. Copy all three files together, crm.db, crm.db-wal and crm.db-shm.

Your Contact Cadence Settings Are Ignored

Symptom. You changed a cadence in .prima-crm/config.json, but stale companies still follow the old numbers. The server log shows PRIMA CRM: <path> could not be parsed, using defaults followed by the parse error.

Cause. The file is not valid JSON. The server leaves it as it is and uses the defaults, which are 30 days for clients, 60 for partners, 90 for suppliers and no cadence for internal and other.

Fix. Correct the syntax the message names, then restart Claude Code. See Configuration.

A Company Never Appears as Stale

Symptom. A company has had no contact for months, yet crm_company stale does not list it.

Cause. Only active companies with a cadence can be stale, so leads and past companies never appear. A company with no relationship set and no project links counts as other, which has no cadence.

Fix. Ask Claude to set the company’s relationship, for example to client, or to give it its own contact_cadence_days. See Stale Clients and Contact Cadence.

Claude Cannot Write the Dormant Status

Symptom. Claude reports status 'dormant' is a legacy value and cannot be written., or a company profile shows the status with a note to change it.

Cause. The dormant status belongs to an earlier version. Stale contact is now worked out from the cadence, so nothing writes dormant.

Fix. Ask Claude to set the company to active or past.

A Project Shows as Not in State

Symptom. Linking a company to a project returns Warning: <id> was not found in state.json. The link is stored, but check the project ID is correct., or a table shows NOT IN STATE in place of the project name.

Cause. The project ID is not in your project register, but the CRM keeps the link anyway.

Fix. Check the project ID against /status. If the ID has a typing error, ask Claude to unlink the wrong ID and link the right one.

A Mislogged Record Cannot Be Removed

Symptom. Claude logged an interaction or created a contact by mistake, and cannot delete it.

Cause. No PRIMA CRM tool deletes or edits interactions, and no tool deletes contacts, engagements or segments. Duplicate companies are the one case with a supported fix, through merge.

Fix. Ask Claude to correct the fields the CRM lets it update, for example a contact’s details or an engagement’s stage. For duplicate companies see the next entry, and for anything else see Getting Help.

A Merge Changes Nothing

Symptom. Claude reports DRY RUN — no changes made. after a merge request.

Cause. A merge shows a preview first and makes no change until you confirm it.

Fix. Read the preview, then tell Claude to go ahead. A merge also stops with Source and target are the same company., Source company <id> not found. or Target company <id> not found. when the IDs are wrong.

Interaction Sync

Sync Shows Not Built Yet and Review Is Always Empty

Symptom. crm_sync status lists your email, calendar or meetings provider as Not built yet, and crm_sync review returns Nothing staged for review.

Cause. This release has no code that fetches from a provider. It has source discovery, classification and approval, but not the fetching step. See Email, Calendar and Meeting Sync.

Fix. You do not need to change anything. Log contact yourself by telling Claude about it, as described in Interactions.

Sync Says There Is No integrations.json

Symptom. crm_sync status reports No integrations.json found in this workspace. although the file exists.

Cause. The CRM reads .claude/config/integrations.json and treats a file it cannot parse as missing. Values still holding template text, such as a list separated by |, a value starting with [ or <, or the word none, count as not filled in.

Fix. Ask Claude to check the file for JSON syntax errors and to replace any template values with your real provider and connector names.

Claude Cannot Accept or Discard a Staged Item

Symptom. Claude reports one of these messages.

Message	Fix
Staged ID "<id>" is too short. ...	Give at least the eight characters crm_sync review shows
No pending staged item matches "<id>". It may not exist or may already be resolved.	Run crm_sync review again and copy the ID from the current list
Staged ID "<id>" matches more than one pending item (...). Pass more characters or the full ID.	Give more characters of the ID
Pass contact_id for an existing contact, or create_name and create_company to promote a lead.	Tell Claude who the item belongs to, or ask it to create the person as a new lead

Errors From Claude’s Requests

Claude Reports an Invalid Value

Symptom. Claude reports a message that starts Invalid relationship, Invalid contact_cadence_days, Invalid source_category, Invalid type, Invalid stage or Invalid relation, or says A project cannot be related to itself.

Cause. The request used a value the CRM does not accept. Each message lists the values the CRM accepts.

Fix. Ask Claude to try again with one of the listed values. Messages such as Unknown contact action or id is required for update mean the request itself was incomplete, and Claude can correct it. See Tools Reference.

The Dashboard

The Dashboard Script Says There Is No CRM Database

Symptom. Building the CRM dashboard stops with No CRM database at <path>. Run from your workspace root.

Cause. The script looks for .prima-crm/crm.db in the folder you run it from.

Fix. Run it from your workspace root.

node .claude/mcp-servers/prima-crm/scripts/build-dashboard.mjs

The Today View Names a Command You Do Not Have

Symptom. In PRIMA Project Management’s Today view, a banner says it could not read the CRM and suggests running /crmdash.

Cause. No product ships a /crmdash command, and the banner means the Today view could not open .prima-crm/crm.db.

Fix. Run the dashboard script above, and if it builds, the database opens. If it fails, work through The Server Stops at Once and The CRM Is Empty or Shows the Wrong Records.

Still Stuck

See Getting Help.