Cortex Troubleshooting

Work from the outside in: command resolution, version, storage, Bluetooth scan, connection, then device commands. Avoid deleting files or editing PATH until you have identified the exact source.

Use the current voltra app installed on the user's machine. Older Node.js / npm-based VOLTRA command-line installs are legacy and should be replaced with the current app.

Command Resolution

On Windows:

where.exe voltra
Get-Command voltra -All | Format-List Source,CommandType,Definition
voltra --version
voltra -v

On macOS/Linux:

command -v voltra
type -a voltra
voltra --version
voltra -v

If multiple voltra commands are found, report all paths and identify which one runs first. Old install locations or release artifact folders should not be kept in PATH.

PATH Investigation

On Windows, inspect all scopes separately:

[Environment]::GetEnvironmentVariable("Path", "Process")
[Environment]::GetEnvironmentVariable("Path", "User")
[Environment]::GetEnvironmentVariable("Path", "Machine")

Do not modify Machine PATH unless the user explicitly asks and the shell has administrator permission. If a path cannot be removed because registry access is denied, say that clearly and give the exact remaining entry.

Storage

Known devices are local metadata, not live device state. Default storage is:

%USERPROFILE%\.voltra\known-devices.json

VOLTRA API Key config is separate:

%USERPROFILE%\.voltra\config.json

Useful commands:

voltra list-known --json     # alias: voltra devices
voltra scan --json
voltra config show --json
voltra config clear-api-key --json

BLE Diagnosis

Start with:

voltra doctor
voltra ble doctor
voltra scan --json

If scanning fails:

• Make sure Bluetooth is enabled.
• Keep the VOLTRA nearby and powered on.
• On Windows/macOS, check Bluetooth permissions.
• On Linux, follow the voltra doctor guidance.

Connection And Control

Use this order:

voltra scan --json
voltra connect <device-id-or-name> --json
voltra refresh <scope> --json   # e.g. all, epStatus
voltra status --json

Use voltra disconnect --json when the user asks to end the local session or before switching devices. Do not treat disconnect as remote device shutdown.

For version/content drift, use voltra update --check, voltra update, voltra skills list, and voltra skills update. If update fails because of install source or permissions, fall back to reinstalling the latest Cortex package.

If backend policy reports the installed Cortex client as BLOCKED (status=2), every command except voltra update is intentionally disabled. Do not retry doctor, skills, device, cloud, or local commands; update Cortex first. Parser-only --version and help output remain available.

Twin pairing is supported (voltra twin *). Twin cannot run customCurve or sled pull; set-mode customCurve and custom-curve apply are rejected until unpair. set-auto-unload is supported. Note: auto-load, cancel-auto-load, safety-check, set-max-eccentric-percent, and recording are not supported commands — do not invent them.

Daemon & Logs

When the daemon is unresponsive or state seems stale:

voltra daemon status --json
voltra daemon stop --json

Inspect diagnostic logs:

voltra logs path --json
voltra logs tail --json
voltra logs tail --file daemon -n 200 --json
voltra logs upload --message "<support context>" --json
voltra logs clear --json

voltra logs upload creates a safe compressed package, rejects logs containing protocol-sensitive markers, and sends it to the configured support upload endpoint. Run it only after the user explicitly asks to share diagnostics; do not paste API keys or raw protocol payloads into --message. It accepts --case-id, --max-bytes, and --upload-base-url for support workflows.

Irreversible: voltra logs clear wipes all local log files. Confirm with the user before running.

For API/auth failures, verify identity without dumping private data:

voltra whoami --json

For API transport failures from an agent subprocess such as Claude Code, run the read-only diagnostic command in that same subprocess:

voltra diagnostics api --json

The command reports a safe, deterministic diagnosis in addition to the redacted evidence. It checks the configured target, whether a credential is visible to this process, the current executable and parent process, console-handle state, proxy/certificate environment-variable presence, DNS, direct TCP, and the authenticated request. It never prints API keys, authorization headers, or response bodies. A missing or unreadable local key is reported as a credential diagnosis instead of causing the diagnostic command to exit before collecting evidence.

The direct TCP probe bypasses HTTP proxies. To test whether the authenticated HTTP request itself depends on the proxy, run both request modes in the same agent subprocess:

voltra diagnostics api --json --proxy-mode normal --save "$env:TEMP\voltra-diagnostics-normal.json"
voltra diagnostics api --json --proxy-mode direct --save "$env:TEMP\voltra-diagnostics-direct.json"

normal uses reqwest's normal proxy behavior. direct disables HTTP proxy discovery for this diagnostic request only; it does not change the user's proxy configuration. A normal failure plus direct success strongly points to the proxy path. If both fail while DNS and direct TCP succeed, investigate TLS interception, endpoint security, or the agent process boundary. Treat the report's diagnosis.category, confidence, evidence, and nextSteps as the primary interpretation.

Use --save <path> when an agent needs to read the report later or return it to support. The saved file contains the same redacted JSON printed to standard output, and the parent directory must already exist. There is intentionally no CLI compare command; an agent can read two saved reports and explain the differences without adding another stateful command.

Use --api-key <key> only for one-off debugging; prefer VOLTRA_API_KEY or voltra config set-api-key to avoid shell-history leaks.

For control failures, preserve Cortex's message. Do not retry indefinitely when Cortex says:

• Place the device on the dock first.
• Load blocked: place the device on the dock first.
• Load blocked: cable is not on zero position.
• Load blocked: choose a training mode first.

Cross-References

• If troubleshooting reveals the user is a first-time user who has not completed setup, suggest loading voltra-getting-started.
• After resolving connection issues, load voltra-device-status to verify the device state.
• After resolving issues during a training session, load voltra-device-training to safely resume control.
• For workout data issues (auth, missing history), load voltra-workout-data.
• For the full Cortex command reference including daemon, logs, sessions, skills management, and custom curves, see voltra-device-training references.