Troubleshooting
Diagnose missing connectors, authentication failures, Claude errors, and invalid local state.
Connector is not listed
Check the path
The default file is config/connectors.json. Confirm PRAXIS_CONNECTORS_PATH, PRAXIS_CONFIG_DIR, and PRAXIS_WORKSPACE_DIR are not pointing elsewhere.
Validate the file
The root must contain a connectors array. Each id must use lowercase kebab-case and every base URL must be valid.
curl http://localhost:3000/api/connectorsConnector is unreachable
Call the status route with an explicit id. A missing token reports configured: false. A failed ping reports configured: true and ok: false.
curl 'http://localhost:3000/api/connectors/status?id=acme-crm'Verify the base URL, ping path, DNS/network access, and the environment variable named by tokenEnv.
Operations fail
Open the failed operation before changing code. The attempt contains the capability, chosen mechanism, exact prepared request, remote response or error details, classification, and retryability.
| Error kind | First check |
|---|---|
| configuration-needed | Capability endpoint, connector id, and token |
| access-denied | Remote credentials and permissions |
| invalid-request | Rendered path/body and remote API contract |
| system-unavailable | Ping, network, and remote service health |
| unsupported | Whether the selected transport implements that capability |
AI falls back
The organic decision note contains the generation failure. Confirm the CLI is installed and authenticated in the same environment that runs Next.js, then check model name, budget, timeout, and workspace permissions.
${PRAXIS_CLAUDE_COMMAND:-claude} --versionFallback is expected to keep the simulation moving. Set aiEnabled: false and evaluatorMode: "deterministic" if you want an explicitly model-free run.
State resets unexpectedly
On load, Praxis replaces state that is missing or fails the current schema. Look for an older .praxis/state.json, a changed PRAXIS_DATA_DIR, or multiple processes using different working directories.