# Troubleshooting

Fix VentilatePro installation, PATH, login, token scopes, MCP connection, validation, and note sync errors with actionable recovery steps.

Canonical: https://ventilatepro.com/exam/cli/troubleshooting/

Documentation version: VentilatePro CLI 0.8.4

## Authentication failures

- If login fails immediately, verify the base URL and the copied token value.
- If `auth whoami` fails after a previous login, the token may have been revoked or expired.
- Use `ventilatepro auth logout` to clear local credentials, then log in again with a new token.
- Revocation happens in the VentilatePro web UI, not from the CLI.

## Project and note access

- If `projects list` returns nothing, the authenticated user does not currently have access to any projects.
- If `notes list` or `notes create` returns a project access error, confirm that the project ID belongs to the logged-in user or a shared project membership.
- If `notes show` fails, verify both the `note\_ref` and the `--project` argument.

## MCP and AI-agent setup

- Run `ventilatepro mcp doctor` before configuring the AI client. It checks login, Agent Editor scopes, catalog loading, and identity.
- If doctor reports missing scopes, create a new `Agent Editor` token. Existing tokens are not silently expanded.
- If the client cannot find `ventilatepro-mcp`, run `where.exe ventilatepro-mcp` on Windows or `which ventilatepro-mcp` on macOS/Linux and configure the full path.
- After changing MCP configuration, restart or reconnect the client so it reloads the server catalog.
- Keep the token out of MCP JSON. The local server reuses the credential saved by `ventilatepro auth login`.

## Queue and sync behavior

| Situation | Queued? | What to do |
| --- | --- | --- |
| Network error | Yes | Run `ventilatepro notes sync` after connectivity returns. |
| Server 5xx | Yes | Retry later; the queued note keeps the same idempotency key. |
| Auth error | No | Fix credentials and rerun the command. |
| Validation error | No | Fix the command arguments or payload and rerun. |

## Exit behavior

- `notes create` returns exit code 0 when the note is created immediately.
- `notes create` also returns exit code 0 when the note is safely queued locally.
- `notes create` returns non-zero for hard failures such as auth or validation problems.
- `notes sync` returns non-zero when one or more queued notes still fail during the retry run.

## Install and upgrade issues

- Preferred install path: `pipx install ventilatepro-cli`
- Preferred upgrade path: `pipx upgrade ventilatepro-cli`
- Fallback install path when `pipx` is unavailable: `python -m pip install ventilatepro-cli`

[Contact support](https://ventilatepro.com/exam/support/)

## CLI and MCP failure recovery reference

| Symptom | Check | Recovery |
| --- | --- | --- |
| Executable not found | `where.exe ventilatepro-mcp` on Windows; `command -v ventilatepro-mcp` on macOS/Linux | Run `python -m pipx ensurepath`, reopen the terminal/client, or configure the absolute executable path. Escape Windows backslashes in JSON. |
| Local status says authenticated, but calls fail | `auth status` checks saved credentials; `auth whoami` makes a live request. | Verify the base URL, token validity, and account using `ventilatepro auth whoami`. |
| 401 or OAuth reconnect required | Expired/revoked credentials or the wrong authentication mechanism | Reconnect OAuth for remote MCP; log in with a valid personal token for CLI/local project tools. |
| 403 or missing scopes | Granted scopes and project membership | Use the appropriate token preset and verify project access. Doctor expects the full Agent Editor scope set; narrower access may be intentional. |
| 404 for a record | Record ID, typed reference, project context, and permissions | Rediscover the record from an authorized list. Do not assume an inaccessible ID proves deletion. |
| Validation, confirmation, or stale-review error | Field errors, tool schema, current review revision | Correct inputs or fetch a fresh review. Inspect changes before confirming; do not blindly retry. |
| 429, server failure, or network timeout | Rate-limit information, connectivity, and whether the operation was accepted | For reads, retry with bounded backoff and honor Retry-After when supplied. For writes, reconcile state or use the operation's existing idempotency key before retrying. |
| Local MCP works in terminal but fails in a desktop client | Executable path, OS user, config directory, and keyring availability | Run the client in the intended user context. `VENTILATEPRO_CONFIG_DIR` and `VENTILATEPRO_DATA_DIR` override local paths; they are not independent keyring identities. |

For a support request, include the package version from `pipx list`, operating system, client name, sanitized command, error, and whether an offline calculator succeeds. Doctor output can include your identity; redact personal and project data before sharing. Never send tokens, Authorization headers, or `config.json`.