Troubleshooting
Ordinary users should not edit Praxis source to work around a defect. Distinguish your configuration from a Praxis bug.
| Symptom | Likely class | What to do |
|---|---|---|
PRAXIS_RUNTIME_UNAVAILABLE | config | Enable praxis-runtime.mcpb. Do not launchctl. |
JIRA_CONFIG_UNAVAILABLE | config | Settings → Extensions → Praxis Runtime → Settings |
| Invalid plugin ZIP path / nested folder | config | ZIP must have .claude-plugin/plugin.json at archive root |
Zip file contains path with invalid characters | product (alpha.27) | Use current claude-plugins/*.zip (no node_modules/@praxis paths) |
Plugin contains a top-level bin/ | product (alpha.28 hosted) | Use current skills-only ZIPs |
MCP handshake timeout / REQUEST_TIMEOUT | product (alpha.29 parser) | Use alpha.30+ Runtime (serveStdio) |
| Four Praxis MCP processes | config + old ZIPs | Uninstall pre-alpha.31 role plugins that bundled MCP |
| Missing Runtime configuration / empty token after update | config | Re-enter settings; Update |
| Localized issue types (translated Story/Bug names) | handled | Runtime uses numeric type ids |
| Duplicate BA Stories | product+data | Canonical vs superseded; do not create a fourth |
| BA/Architect preview timeout | product (alpha.32) | Current Runtime; retry preview; do not apply blind |
| Unexpected multiple Work Packages | product (alpha.33) | Hard WP id scope; preview one WP |
Title --- | product (alpha.33) | Invalid title; fix design title, re-preview |
| Invalid Jira transition identifier | config/product (alpha.34) | Must be discovered numeric id; localized names are not ids |
| Claim conflict | data | Other actor holds claim |
| Complete moved Jira to Done without QA | product bug alpha.34 | Do not treat completed=true as success. Use recovery preview, separate YES, then complete/evidence. Manual live repair is not automatic |
| Missing completion evidence / Quality handoff | follows alpha.34 | Developer complete (alpha.35+) or gated recovery |
| Quality runtime unhealthy / not_started | Quality-only | Call praxis_quality_ensure. Does not block BA/Architect/Developer |
QUALITY_PACKAGE_MISSING | product/distribution | Runtime MCPB must include server/praxis-quality.cjs. Reinstall current Runtime. Do not npm start |
QUALITY_STARTUP_FAILED / QUALITY_PROCESS_EXITED | product/host | Read stage, nodeExecutable, exitCode, and logPath under .praxis-quality/. Do not install Node or SQLite by hand. Do not edit Praxis source |
QUALITY_SPAWN_FAILED / QUALITY_EXECUTABLE_NOT_FOUND / QUALITY_EXECUTABLE_NOT_PERMITTED | product/host | Quality could not start a child runtime. Reinstall current Runtime (alpha.38+). Do not install Node by hand |
QUALITY_SQLITE_UNAVAILABLE / QUALITY_SQLITE_MODULE_LOAD_FAILED | product/host | The Desktop Node child could not load node:sqlite; current Runtime should fall back to packaged sql.js. Reinstall alpha.37+ Runtime. Do not npm install sqlite3 |
QUALITY_CHILD_RUNTIME_MISMATCH | product/host | MCP Runtime and Quality child used incompatible executables. Reinstall current Runtime. Do not point PATH at a homemade Node |
GITHUB_API_URL_INVALID | config | Runtime GitHub API URL must be https://api.github.com (or https://HOST/api/v3). An SSH git remote is not an API URL |
GIT_REMOTE_REQUIRED | config | Connect Git after the user names a URL. Do not guess GitHub/GitLab |
GIT_IDENTITY_REQUIRED | config | Set Git user.name/email (preview + YES). Do not copy Jira email silently |
GIT_QUALITY_SNAPSHOT_MISMATCH | data | Files changed since QA. New Quality Review; do not Apply from Git |
GIT_BASELINE_REQUIRED | data | Empty GitHub repo needs approved baseline push before a PR |
GIT_FORCE_PUSH_FORBIDDEN / remote history conflict | safety | Praxis never force-pushes |
GITHUB_TOKEN_UNAVAILABLE | config | Runtime GitHub Token (PAT). Never paste into chat |
GIT_SECRETS_DETECTED | safety | Committed objects look like credentials. Publish is blocked. Values are not shown |
ciStatus=not_configured | expected | No GitHub Actions workflow in the committed tree. This is not CI PASS |
Baseline preview targets master on GitHub main | product (alpha.43) | Install a Runtime release that includes GitHub Delivery baseline-to-main. Refspec must be <SHA>:refs/heads/main |
Partial git write (writeSucceeded / verification failed) | expected | Outer MCP ok is false. Retry the same fingerprint. Do not force-push |
QUALITY_HEALTH_TIMEOUT / QUALITY_DB_INIT_FAILED | product/host | Bounded wait failed. Retry ensure; check .praxis-quality/quality.log |
LOCAL_RUNTIME_UNAVAILABLE | config | Cowork local access + folder |
| Stale preview fingerprint | expected | New preview. Do not apply an older hash after generating a new preview (including after a Runtime upgrade). |
QUALITY_PREVIEW_STALE | expected | Jira status, transition id, or transition target changed before Apply wrote anything. New preview, then new YES. |
QUALITY_RECONCILIATION_REQUIRED | data | Jira is already Done but this Apply journal cannot prove it did the transition. Inspect status; do not invent success. |
Quality Apply ok=false / partial=true | expected | Some actions committed, others pending. Retry the same fingerprint. Do not treat MCP outer ok as success when data.ok is false. |
Developer status qualityState=pending after Apply | product (alpha.40) | Install alpha.41+. Status must follow praxis.state / local manifest, not status=ready-for-qa. |
Quality worker stopped / unknown between Desktop turns | host/product | Worker mode lives in the Runtime MCP process. Call praxis_quality_ensure again. Read lastKnownPid, lastExitCode, logPath. Do not invent a Cowork cause. |
CLI remains for CI (praxis doctor --json). Desktop users should stay on Skills.
If PRX-4 is live Done from alpha.34: use the recovery prompts — preview, stop, approve recovery separately. Tests never mutate live Jira.