Troubleshooting

Context is missing or stale

Ask the agent which files it actually read. Check the vault root, project path, selected adapter, saved bytes and current review state. Pro context may also need the correct activation state. A previous chat message is not proof of a saved file.

If two sources disagree, identify which is authoritative and review the correction. Do not silently promote a proposal into a decision. Repeat the fresh-session check after the fix.

Installation will not proceed

Symptom	Next step
Nonempty target with Community new	Choose a fresh destination or the correct enhance/upgrade route
Approval required	Read the plan, then explicitly authorize the intended change
GLOBAL_OVERWRITE_FORBIDDEN	Remove overwrite requests and review individual proposals
BACKUP_SETTING_UNSUPPORTED	Keep an independent snapshot; remove the obsolete backup_before_migration answer
LINK_RESOLUTION_REGRESSION	Qualify the conflicting link on a backed-up test copy, then replan
Pro source is blocked	Read the guided compatibility result; do not remove authority records

Interrupted operation

Stop competing writers and preserve the package, journal, backups and run/transaction identifier. Determine whether the original writer is still active. Do not delete a lock until you have established that it is stale. Use the matching recovery procedure.

Community exit codes

Code	Meaning
2	Input, planning, approval or validation issue
3	I/O failure; inspect the journal
4	Incomplete rollback; inspect retained changes

Pro validator output and exit codes

The installed Pro validate-kos.ps1 writes JSON containing result, errors, warnings, info and findings. Check the command’s exit code as well as its output:

Code	Meaning	Next action
0	Validation passed	Continue with installation and fresh-session checks
1	Warnings, without errors	Review each warning before relying on the vault
2	Errors or blocked validation	Resolve the reported findings before proceeding
3	Execution failure or invalid input	Inspect stderr, arguments and the selected script

These codes describe the installed validator, not every installer command. In an adopted legacy vault, verify which validator belongs to the installed Pro package before interpreting its result.

Installer errors prefixed KOS-INPUT: identify an invalid argument or invocation. Do not combine -Interactive with apply/license/planner overrides. For a source-compatibility block, retain the inspection report and use a supported source rather than removing identity records.

Community resume is intentionally blocked

RESUME_REQUIRES_JOURNAL_REVIEW means Starter Kit 1.2.0 will not repeat interrupted writes through -Resume. Follow Community recovery, inspect the rollback result, then run a new dry-run. See the tagged operation guide.

A command is missing

Check edition and package version. Community and Pro do not ship identical tools. For Pro 1.1.0, use Get-KOSContextManifest.ps1; do not assume a private helper named Get-KOSProjectContext.ps1 is installed.

Before asking for help

Collect the exact sanitized error, versions, operating system, operation, expected result and minimal reproduction. Keep private notes, credentials and identifying paths out of the report. See support.