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.
Approvals, installation and diagnostics
Start with praxis_doctor for the repository: approval.mode, approval.trust, approval.client, approval.dialogAutomation, build, nextSteps. See Diagnostics. Since 0.1.0-alpha.49.2 protected actions are approved only in the client's own dialog (Approvals).
| Symptom | Cause | Fix |
|---|---|---|
A protected apply returns APPROVAL_CLIENT_UI_REQUIRED, result says "NOT executed", executed: false, preview attached | Praxis could not ask here (approval.mode: no-dialog). In Claude Desktop this is expected: Chat and Cowork show no dialog, and the Code tab answers its dialog by itself (approval.observedDialog) and is started with settings Praxis cannot check. Nobody rejected the action. Nothing the agent or you type can substitute, and no setting turns this off | Apply it from the Claude Code CLI in a terminal, in the same repository, and approve it in the CLI's dialog. Read-only tools, previews and reviews keep working in Desktop |
In the Claude Code CLI a protected apply returns APPROVAL_CLIENT_UI_REQUIRED, and approval.dialogAutomation lists a file, flag or variable | Praxis found configuration that could answer the dialog: an Elicitation hook, a client started with settings, plugins or agents on its command line, an environment that points the client at more configuration, or a repository .claude/settings.json that holds more than plain preferences (any hook, any env entry, a status line command, plugins) | Move hooks and env from the repository's settings into your user settings, start claude without those flags and not inside another Claude Code session, then ask again. The doctor names what it found |
| A protected apply in Claude Desktop Chat shows no result for minutes (the 4-minute hang seen in a real test) | Desktop's own tool-permission prompt holds the call before it reaches Praxis. Desktop's log has tool_approval_gate ... approvalRequired:true; Praxis has no tool_enter for the call | Find the permission prompt in the Desktop window and answer it. Allowing the call lets it reach Praxis; it does not approve the action, which Praxis then refuses in Desktop. Check ~/.praxis/diagnostics/mcp.jsonl: tool_enter then tool_finished means Praxis answered; no tool_enter means Desktop never passed it on. "Allow once" is safer than "Always allow" |
APPROVAL_TIMED_OUT | The client declared a dialog but nobody answered within 10 minutes. Nothing executed. Neither a rejection nor an approval | Ask the agent to run the apply again to get a new dialog |
APPROVAL_REJECTED | Reject was chosen in the client's dialog | Nothing was changed. Ask for a new preview if you want to proceed |
APPROVAL_DISMISSED | The dialog was closed without deciding. Not a rejection | Nothing was changed. Ask the agent to run the apply again |
APPROVAL_WITHDRAWN | The agent passed confirmation=NO. Not your decision | Nothing was changed. Ask for a new preview if you want to proceed |
APPROVAL_FINGERPRINT_MISMATCH | The previewFingerprint no longer matches the live plan: the repository, Jira or workflow state changed after the preview | Run the matching *_preview tool again, show the new preview, then apply |
APPROVAL_SCOPE_MISMATCH or APPROVAL_EXPIRED | The approval was for different content, or older than 10 minutes | Preview and approve again |
APPROVAL_REQUIRED | A mutation was attempted outside an approved Praxis action (for example a direct library call) | Run it through the apply tool |
JIRA_CONFIG_UNAVAILABLE: missing jira_base_url, ... | A Jira tool was called without the needed settings. Local tools are unaffected | Set the missing settings (extension settings, or PRAXIS_JIRA_* environment variables for CLI and plugins). Do not paste tokens into chat. Not needed for local workflows |
A Jira, GitHub or GitLab setting shows as blank or as ${user_config...} | A blank optional extension setting | Ignore: it is treated as unset and listed in hostPlaceholdersIgnored |
PRAXIS_RUNTIME_UNAVAILABLE (reported by a role skill) or no praxis_* tools in the client | The Runtime is not connected in this client. Claude Code, Desktop Code, Cowork get it from the praxis-runtime plugin; Desktop Chat from praxis-runtime.mcpb; Web Chat has none | Install through the marketplace (claude plugin install praxis@praxis) or install praxis-runtime.mcpb in Desktop Chat. Start a new session. Check claude plugin list |
| A role skill is installed but the Runtime is not | The role plugin was installed from a ZIP, or praxis-runtime was disabled or removed. Dependencies are declared only in marketplace entries, so a ZIP does not bring the Runtime | Install the role from the marketplace (claude plugin install praxis-ba@praxis installs praxis-runtime as a dependency), or enable praxis-runtime |
Old behaviour after an update, wrong tool count, older build.version | A stale old extension or plugin: a session started before the update keeps its tool list, or an older installation is still loaded | Quit the client completely and open a new session or chat. Compare build.bundleSha256 and build.tools.count (expected count in Compatibility) with the installed file. For Desktop, uninstall the old extension before installing the new .mcpb (the version string may be unchanged). npm run report:tool-origins in praxis-runtime lists the origins |
Two sets of identical praxis_* tools, or protected calls answered inconsistently | Duplicate Runtime: the praxis-runtime plugin and the .mcpb extension are both active in the same client, or an old copy is still enabled | Keep one. Desktop Chat uses the .mcpb; Code and Cowork use the plugin. Disable or uninstall the other. A marketplace install yields exactly one server |
| Quality tools answer from an old service, port 8792 busy | An old Quality service process kept the port and answers for the new Runtime | Quit the client, find the old process (pgrep -fl "praxis-quality.cjs|praxis-mcp.cjs"), stop it if it is the old Praxis service, reopen. praxis_quality_status and praxis_quality_ensure show the state |
dotenvRejected lists keys | A repository .env tried to set PRAXIS_APPROVAL_*, PRAXIS_ALLOW_*, PRAXIS_FIXTURE_* or PRAXIS_TEST_*; they were ignored | Remove them from the file. There is no approval setting: approval comes only from the client's dialog |
PRAXIS_APPROVAL_MODE or the Desktop extension's Approval mode does nothing; approval.ignoredEnvironment lists it | Trusted Client and host-permission were removed in 0.1.0-alpha.49.2. No setting, file or environment variable weakens approval | Remove the variable or the setting's value. Apply protected actions from the Claude Code CLI and approve them in its dialog |
PRAXIS_MCP_ROLE_INVALID or PRAXIS_MCP_START_FAILED on stderr | The server was started with a wrong --role (expected ba, architect, developer, quality or runtime), or failed to start | Use the shipped plugin or MCPB (--role runtime). Check Node.js is 20 or newer |
WORK_ITEM_SELECTION_REQUIRED | A fresh clone has several work items and no current selection | Pass workItemId, or run the select-work-item workflow command |
WORKFLOW_CONFLICT | A legacy state.json and items/ both exist | See PRAXIS-STATE-POLICY.md in praxis-runtime |
Not verified: behaviour of the Claude UI plugin manager; marketplace install in Claude Desktop Chat; the real Desktop Chat and Cowork interfaces with 0.1.0-alpha.49.2.