Troubleshooting

Each section below starts with what you see, then gives the cause and the fix. Most problems with the project register show up when you run the validation script, so start there when something looks wrong.

Scripts/validate-state.sh

The Project Register

No state.json Found

Symptom. /dashboard stops with No state.json found. Run /setup to initialise PRIMA, or create .claude/state/state.json manually. Other commands report that the state file is missing.

Cause. .claude/state/state.json does not exist in the folder Claude Code has open. Either the workspace has not been set up, or Claude Code is open in a different folder.

Fix. Check that Claude Code is open in your workspace folder. If it is, restore the latest copy from .claude/state/backups/ when that folder holds one. The installer from the email you receive when you buy creates state.json, and /setup only fills it in, so a workspace with no register and no backup needs the installer run again. Claude does not create the file by itself, and Getting Help explains how to get support.

Validation Fails

Symptom. Scripts/validate-state.sh prints a line marked with a cross and stops, or Claude reports that a write to the register failed validation.

Cause. The register breaks one of the checks the script makes. When a write fails, Claude restores the backup taken just before it.

Fix. Find the message in the table and correct state.json, then run the script again.

Message	Cause	Fix
Invalid JSON in ...	The file has a syntax error	Restore the latest backup (see below) or correct the error
Missing required field: version (or workspace, projects)	A top-level field is missing	Add the field back
Invalid workspace type: ...	workspace.type is not personal, client or internal	Change it to one of those three
Duplicate project ID: ...	Two projects share an ID	Give one of them the next unused ID
Invalid project ID format:	An ID is not one to ten letters, an optional hyphen and three to six digits	Correct the ID, such as P012
Invalid status value(s):	A status other than in-progress, paused, overdue or archived, such as blocked or active	Change it to one of the four
Schema validation failed	The file breaks the schema, checked only when ajv-cli is installed	Compare the file with .claude/state/state.schema.json

Validation Passes With Warnings

Symptom. The script ends with State validation passed but prints lines marked with a warning sign. The final report of /night lists the same warnings.

Cause. Warnings report problems that do not stop the register working.

Fix. Correct each one when you can.

Warning	Fix
Workspace identity incomplete	Fill in name, id and type in the workspace object
Duplicate project name detected	Rename one project, or archive the duplicate
Project IDs use more than one format	Leave existing IDs as they are, and choose one format for new projects when /newproject asks
Project(s) missing category or Invalid category value(s)	Set category to one of the ten values in the schema
Paused project(s) without reason	Add a pausedReason to each paused project
Session history holds ... entries from before ...	Run Scripts/archive-history.sh, which moves them into the monthly archive

The Register Is Damaged

Symptom. Commands report JSON errors, or projects and fields are missing.

Cause. A failed edit or a sync conflict has damaged state.json.

Fix. Restore the most recent good backup from .claude/state/backups/, then validate the result.

cp .claude/state/backups/2026-10-13.json .claude/state/state.json
Scripts/validate-state.sh

Caution

A restore replaces your register with the backup copy. You lose every change made after that backup was taken.

Backups Keep Piling Up

Symptom. .claude/state/backups/ holds many files.

Cause. The backup script saves one copy per day.

Fix. You need to do nothing, because each backup run deletes copies older than 30 days. Keep the folder out of your commits, which the AI Business OS .gitignore already does.

Projects

New Project Stops on Mixed ID Formats

Symptom. /newproject stops, shows one example of each ID format in your register and asks which format to use.

Cause. Your register holds IDs in more than one format, such as P012 and PRJ-0013.

Fix. Choose one format for new projects, and Claude leaves every existing ID unchanged.

Possible Duplicate Found

Symptom. /newproject or a request to add a project stops with Possible duplicate found and three choices.

Cause. A project with the same or a similar name exists, archived ones included.

Fix. Choose “Use existing project” to carry on with it, which returns an archived project to in-progress. Choose “Create new” only when the work differs, and say how.

No Projects on the Timeline

Symptom. /timeline reports No projects have delivery dates set.

Cause. No project has both a startDate and a dueDate.

Fix. Ask Claude to set the dates, such as “set P012 to start 1 September and finish 20 November”, then run /timeline again.

Pushing and Syncing

Workspace Mismatch

Symptom. /sync or /night stops with WORKSPACE MISMATCH, showing the expected repository and the actual remote.

Cause. workspace.githubRepo in your register does not match git remote get-url origin. Either Claude Code is open in the wrong workspace, or the register holds an old repository name.

Fix. Check first that you are in the right workspace, and if you are, run git remote get-url origin and set workspace.githubRepo to match. An empty string switches the check off.

The Daily Briefing

Calendar Events Missing

Symptom. /day shows Integrations: Not configured or Calendar: MCP not available, or the Today view says “No events file”.

Cause. Any of four things can cause this, starting with a missing .claude/config/integrations.json or a calendar.enabled setting of false. The calendar connector is not set up in Claude Code, or it needs you to sign in again on this computer.

Fix. Set calendar.enabled to true in .claude/config/integrations.json, which the installer creates. Check that the calendar connector named in calendar.mcp works in Claude Code, and sign in again if it asks.

Resume Gives Less Detail Than Expected

Symptom. /resume shows checkpoint and register details only, and says PRIMA Memory gives fuller recall.

Cause. PRIMA Memory is not installed or not running.

Fix. Nothing is broken, because /resume falls back to checkpoint files and your register. For searchable session history, see Installing PRIMA Memory.

The Dashboard

Node Not Found

Symptom. /dashboard or the Today view in /day fails with an error that node is not found, or the build fails on an old Node version.

Cause. The build script needs Node 18 or later.

Fix. Install or update Node, then run /dashboard again, knowing that every other command works without Node in the meantime.

Template Missing or Damaged

Symptom. The build stops with Dashboard template not found at ... or Template injection point not found, or Claude says the build script is missing.

Cause. .claude/templates/dashboard-template.html or Scripts/prima-dashboard/build-dashboard.mjs is missing, or someone has edited the template and removed the marker where the data goes.

Fix. Reinstall PRIMA Project Management or run /update, which restores both files. Do not edit the template by hand, because it is a protected file.

Build Fails With Another Error

Symptom. The build stops with Dashboard build failed: and an error message.

Cause. Something unexpected went wrong, for example a project detail file or task file that is not valid JSON.

Fix. Read the error, which names what failed, and check any files under .claude/state/projects/ and .claude/state/tasks/ for JSON errors.

Page Shows No Icons

Symptom. The page opens but icons are missing and the font looks wrong.

Cause. The page loads its icons and font from the assets/ and fonts/ folders beside it. They are missing when you move or send the HTML file on its own.

Fix. Keep the page in Documentation/Reports/, or copy both folders with it. Running /dashboard again puts them back beside the page.

Projects Missing From the Dashboard

Symptom. A project in your register does not appear.

Cause. The build leaves out archived projects unless their due date is within 30 days of the build date.

Fix. The build works as designed here, and /status shows your archived projects.

Recent Activity and Meetings Are Empty

Symptom. The Recent activity panel says “No recent activity recorded yet.”, the Calendar view shows no meetings, and Project Detail shows no sessions.

Cause. These read the session history on each project, which /night and /save write for the projects you worked on. A project you have not closed or saved a session on this month has no entries here, and earlier months are in the monthly archive.

Fix. Run /night at the end of each session, or /save during it, and rebuild the dashboard. The Where You Left Off panel on the Today view shows your last session in the meantime.

Projects Marked At Risk

Symptom. Projects show “At risk” in place of their status, and the build summary lists untracked work.

Cause. The projects have task files, were worked on in the last 14 days, and show no task movement in that time.

Fix. Update the task files, or switch the marking off with taskEnforcement.enabled: false in state.json. Tasks and Dependencies explains the settings.

Today View Banner Says Events Are Old

Symptom. A banner reads Events file with Fetched on and an earlier date.

Cause. /dashboard reused the events file from an earlier /day.

Fix. Run /day to fetch today’s events.

Today View Banner Says PRIMA CRM Failed

Symptom. A banner reads PRIMA CRM failed with an error, and the fix line tells you to run /crmdash.

Cause. The build could not open .prima-crm/crm.db. It uses the SQLite driver from the PRIMA CRM install in .claude/mcp-servers/prima-crm/, and otherwise falls back to the SQLite module built into Node, which older Node releases do not include.

Fix. Neither product ships a /crmdash command. Test the database by running the PRIMA CRM dashboard script from your workspace folder.

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

If that script also fails, see PRIMA CRM Troubleshooting.

Today View Banner Says Folder Not Found

Symptom. A banner reads Content pipeline with Folder not found.

Cause. contentPipeline.runsDir in .claude/config/prima-dashboard.json names a folder that does not exist.

Fix. Correct the path, which is relative to your workspace folder, or delete the file to hide the panel.

The Page Does Not Open by Itself

Symptom. The build succeeds but no browser opens.

Cause. /dashboard gives open steps for macOS and Linux or WSL only, and /timeline gives none for Linux.

Fix. Open the file from the path in the summary in any browser.

Health Check

Critical File Modified

Symptom. /status shows ⚠️ Critical file modified with a file path.

Cause. A protected file differs from the copy in the PRIMA Project Management source folder. This happens when someone edited it, and also when the source folder holds a newer release than the one installed.

Fix. Run /update to restore the released version. Put any change you want to keep in a companion rule file, as Rules It Installs describes.

Note

/status looks for the source folder in ~/prima-plugin or in other common places that the command does not name. When it cannot find one, it leaves out the health check without saying so. A workspace installed from the email you receive when you buy usually has no such folder, so the check does not run there.

Getting More Help

If your problem is not listed here, see Getting Help.