Troubleshooting

Each section below starts with what you see, then gives the cause and the fix. Messages in code style are the exact text the workspace prints.

Updating

Update Stops Because a Tool Is Missing

Symptom. /update stops with Error: jq is not installed or Error: git is not installed.

Cause. The update script needs both tools and checks for them before it starts.

Fix. Install the missing tool, then run /update again. On macOS, install jq with brew install jq, and on Linux or WSL with sudo apt install jq.

Note

The safety guard stops Claude running a system-wide install such as brew install, so run the install command yourself in a terminal.

Update Cannot Find the Manifest

Symptom. The update stops with Error: .claude/engine-manifest.json not found and asks whether you are running it from the workspace root.

Cause. Claude Code is open in a folder other than your workspace folder, or the workspace is missing its manifest.

Fix. Open your workspace folder itself in VS Code, not a folder inside it, and run /update again. If the manifest is missing, the workspace needs a manual update, and Getting Help explains how to get support. The same applies when Claude reports that Infrastructure/Scripts/update-engine.sh is missing, which means the workspace predates the update system.

Update Fails While Fetching

Symptom. The update prints Fetching upstream... and then stops with a git error.

Cause. The script fetches the new release from the upstream repository named in your manifest. The fetch fails when git cannot reach that repository or your computer lacks access to it.

Fix. Check your connection, then check your GitHub sign-in with gh auth status in a terminal. If the fetch still fails, contact support through Getting Help.

PRIMA Project Management Update Skipped

Symptom. The update prints Warning: Could not fetch PRIMA upstream (SSH auth issue?). and PRIMA update skipped. Engine update will continue.

Cause. The script could not reach the PRIMA Project Management repository, often because of a sign-in problem.

Fix. The engine update still applies. Check your sign-in with gh auth status or your SSH keys, then run /update again to pick up the PRIMA Project Management files.

Merge Conflicts After an Update

Symptom. The update lists files under The following files have merge conflicts that need manual resolution:.

Cause. You changed lines in an engine file that the new release also changed, so the script cannot keep both versions by itself.

Fix. Open each file listed and search for <<<<<<<. Keep the text you want between the markers, delete the markers, then commit the result.

git add -A && git commit -m "Update engine to v3.0.2 (resolved conflicts)"

Updating Your Installation explains how the merge works.

Files Updated Without a Merge Base

Symptom. The update reports that files were updated without a merge base (first update on this workspace).

Cause. The script could not find an earlier copy to compare against, so it replaced those files with the new release.

Fix. If you had changed any of the files listed, copy your changes back from .claude/engine-backups/, in the folder named after the version you had before.

Undoing an Update

Symptom. An update changed something you want back.

Cause. Every update saves the engine files it replaces in .claude/engine-backups/, and it commits any uncommitted work just before it starts, as a snapshot you can undo with git revert HEAD.

Fix. Type /update rollback to restore the engine files from the latest backup. If Claude reports No backups found in .claude/engine-backups/, there is no earlier version to return to. The rollback does not restore PRIMA Project Management files, which have their own backups in .claude/prima-backups/.

Blocked Edits and Commands

Claude Cannot Edit an Engine File

Symptom. Claude reports that an edit was stopped with a message that begins BLOCKED: and calls the file a Tier 1 (critical) engine file.

Cause. The engine guard stops Claude’s edit tools changing the files that control how the workspace behaves and updates. Any change to them would be lost at the next update in any case.

Fix. Ask Claude to create a companion file that adds the behaviour you want, such as .claude/rules/my-blocked-commands.md for extra blocked commands. Hooks Overview lists what the guard covers.

Setup Cannot Add Integration Permissions

Symptom. During /setup, the step that adds permissions for your calendar or other integrations to .claude/settings.json reports a block from the engine guard.

Cause. .claude/settings.json is a critical engine file, so the guard stops Claude’s edit tools changing it.

Fix. Add the permissions to permissions.allow in .claude/settings.json yourself in VS Code, or let Claude make the change with a terminal command. The guard checks Claude’s edit tools only. The engine health check accepts extra permissions in this file as long as every engine permission and hook stays in place.

Claude Cannot Run a Command

Symptom. Claude reports a command stopped with a message such as BLOCKED: rm -rf detected. or BLOCKED: sudo detected.

Cause. The safety guard stops commands that can destroy work or change your whole computer. It covers recursive force deletes, force pushes, hard resets, destructive database commands, sudo, scripts piped from the internet into a shell, system-wide package installs and global git settings.

Fix. The guard blocks the command every time, so saying yes to Claude does not let it through. Read the command, and if you want it run, run it yourself in a terminal.

Workspace and Setup

Lock Errors or Empty Object Files in Git

Symptom. Git reports lock errors or object file is empty, or you see merge conflicts nobody caused.

Cause. The workspace sits inside a cloud sync folder, such as Dropbox, OneDrive, Google Drive or iCloud Drive. The sync client and git both work on the same files and get in each other’s way, and iCloud can remove local copies of git’s files.

Fix. Move the workspace out of the sync folder.

1. Copy the workspace folder to a place outside every cloud sync folder, such as ~/Documents/example-consulting/.
2. Open the copy in VS Code from its new location, and carry on working there.
3. Remove the old copy from the sync folder, or stop that folder syncing.

Use git and your remote repository to move the workspace between computers, and keep cloud storage for large files such as PDFs and video.

Running on Windows

Symptom. Scripts fail or behave oddly on Windows.

Cause. AI Business OS needs a Unix shell, and WSL is the supported route to one on Windows. The update script also runs under Git Bash, but the other scripts have not been tested there.

Fix. Install WSL, open your workspace through WSL in VS Code, and run Claude Code there. Requirements gives the platform position.

Claude Does Not Recognise a Command

Symptom. You type a command and Claude does not know it.

Cause. The name is misspelt or in the wrong case, or the command file is not in .claude/commands/.

Fix. Check the spelling, because commands are case-sensitive. Check that the file exists in .claude/commands/, and type /help to see the commands Claude Code has loaded.

The prima-memory Server Fails to Start

Symptom. Claude Code reports that the prima-memory server failed or is not connected.

Cause. The workspace’s .mcp.json registers PRIMA Memory at .claude/mcp-servers/prima-memory/dist/index.js, a file that exists only once PRIMA Memory is installed.

Fix. Install PRIMA Memory, as Installing PRIMA Memory describes. Until then the message is harmless, and the rest of the workspace works without it.

A Connector Stops Working

Symptom. A calendar, meeting or other connector stops answering, or Claude says its tools are not available.

Cause. The connector has lost its sign-in, or Claude Code has not reloaded it.

Fix. Restart VS Code completely. If the connector asks you to sign in again, do so, then try once more.

Project Register

The Register Is Damaged

Symptom. Commands report JSON errors in .claude/state/state.json, or projects are missing.

Cause. A failed edit or a sync conflict has damaged the file.

Fix. Restore the latest good copy from .claude/state/backups/ and run Scripts/validate-state.sh, following the steps in State Files and Validation.

Schema Validation Fails With Custom Project IDs

Symptom. Scripts/validate-state.sh reports Schema validation failed in a workspace whose project IDs use a format other than P001, such as PRJ-0001.

Cause. The script checks the schema only when ajv-cli is installed. In AI Business OS 3.0.2, the schema accepts custom formats for project IDs. It still requires the project IDs listed in each session history entry to look like P001.

Fix. No fix in the workspace is available in this release. The other checks in the script still run, and the failure appears only where ajv-cli is installed.

Skills

A New Skill Does Not Trigger

Symptom. Claude does not use a skill you created when you ask for the task it covers.

Cause. The skill’s description is too vague, or lacks the phrases you would use when asking.

Fix. Rewrite the description with three or four phrases you would say naturally. Test it by asking Claude when it would use the skill.

A Skill Fails to Load

Symptom. Claude Code reports a YAML or frontmatter error for a skill.

Cause. The frontmatter at the top of SKILL.md has angle brackets in it, or the --- lines are out of place.

Fix. Remove any < or > from the name and description. Put each --- line on its own, with no trailing spaces.

Two Skills Compete

Symptom. Claude picks the wrong skill for a task.

Cause. The two descriptions overlap, so Claude cannot tell which one fits.

Fix. Add a line to one description that says which tasks it does not cover and names the other skill.

Lost Context

Claude Has Forgotten Earlier Work

Symptom. In a long session, Claude asks about something you already settled. In a new session, it knows nothing of the last one.

Cause. Claude Code compresses older messages in a long session, and a new session starts with no memory of the conversation. Your files and project register are not affected.

Fix. Run /day for a briefing from your project register, or /resume to pick up a recent session. If a session ended in the middle of a task, paste Claude’s last summary into the new session and ask it to continue. Run /save before a long task, and /night when you finish work, so the next session has a record to start from.

Getting More Help

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