Troubleshoot CodeGraph safely

When CodeGraph fails to start, a project is missing, or analysis returns an error, doctor helps locate the failing area: configuration, project, CPG, or services. Collect the report, select a check for the symptom, and follow its suggested action for the intended project. Before recovery, review the affected data, backup, and rollback plan with the administrator.

1. Capture general diagnostics

Install the CLI using the CLI guide. Open PowerShell at the installed version’s source repository root. Service checks require accessible CodeGraph services.

$env:CODEGRAPH_ALLOW_LOCAL_PYTHON_CLI = '1'
python -m src.cli doctor --json > 'doctor-report.json'
$doctorExit = $LASTEXITCODE
$diagnostics = Get-Content -Raw 'doctor-report.json' | ConvertFrom-Json

Keep the output with the CodeGraph revision, time, environment, project, and user-visible symptom. Redact tokens, credentials, customer source, and personal data before sharing it.

The file is written in the current directory and overwrites the previous report. Ordinary doctor checks return 0 for success, 1 for a warning, and 2 for failure. Inspect $doctorExit and individual check results together. overall_status summarizes the report, primary_issue identifies the main problem, and checks contains results by area. Each check includes id, status, summary and a proposed suggested_action.

1. Capture general diagnostics
`status`	Next step
`pass`	Continue with the other checks in the report.
`warn`	Read `summary` and follow the proposed `suggested_action`.
`fail`	Start recovery from the reported cause, then repeat diagnostics to check the result.
`skip`	Read the reason for the skipped check and prepare its required conditions.

2. Choose a check for the symptom

python -m src.cli doctor config
python -m src.cli doctor project --help
python -m src.cli doctor cpg --help
python -m src.cli doctor openviking --help
python -m src.cli doctor temporal --help

Use explicit --project 'project-name' for project checks. Read the selected subcommand’s help to choose its parameters. For example, if a project graph is stale, choose doctor cpg, supply the project name, and inspect the reasons in its report. doctor openviking requires the employee-memory subcommand and an --employee identifier. Without the subcommand it reports unsupported_openviking_doctor_command. This checks memory availability for the selected employee. It returns 0 for ready and 1 for other statuses.

3. Inspect a local development stack

For an explicitly local source environment:

python scripts/run_app_stack.py status --local --with-mcp
$stackExit = $LASTEXITCODE
python scripts/run_app_stack.py logs --local --with-mcp
$logsExit = $LASTEXITCODE

status reports process states and readiness-check results. For the local stack, $stackExit is 0 when readiness checks pass and required processes are running; 1 requires inspecting the reported reasons.

logs lists paths to service stdout/stderr logs. Open the relevant file and inspect messages from the time of the failure. $logsExit refers to obtaining that path list; retain it with $stackExit.

On a customer Ubuntu deployment, use the systemctl, Compose, and readiness commands from the installation guide.

4. Review a repair plan

Some diagnostic checks support repairs. Inspect the plan before applying changes:

python -m src.cli doctor config --repair --dry-run

Before applying a repair, review its target file, backup, expected result, and rollback plan. After applying it, repeat the same diagnostic check and compare its result with the original report. A dry run lists proposed actions. For invalid YAML, repair creates minimal configuration; restore previous settings from a verified backup.

What to check for each symptom

What to check for each symptom
Symptom	First evidence
Startup/config rejection	`doctor config`, service status, readiness output
Project not visible	`projects list`, `projects resolve-scope`, access identity
Stale or missing graph	import job, `doctor project`, `doctor cpg`
MCP unavailable	API/MCP readiness, `/status`, project binding
Context degraded	`doctor openviking employee-memory`, employee identity, sync state
Workflow delayed	`doctor temporal`, task/session identifier

Start with the selected diagnostic report. Apply data, process and service-configuration changes through the agreed recovery plan.

What to send to support

Provide support with:

exact symptom and expected behavior;
timestamp, environment, release ref, and resolved commit;
tenant/group/project and session or job identifier;
sanitized doctor and readiness output;
steps already taken and whether any state changed.

Reference material

The CLI guide describes diagnostic command parameters and project verification.