Run Diagnostics First
Before digging into a specific error, run the built-in health check. It verifies the five things most conversion failures trace back to: 3XCode's AI runtime, the 3XDE backend connection, your stored credentials, an active workspace, and available system resources.
Terminal
3xcode health
3XCode CLI
Confirms 3XCode's AI runtime is installed and available, since every conversion phase depends on it.
Backend API
Confirms the CLI can reach the 3XDE backend for auth, licensing, and prompt/knowledge retrieval.
Authentication
Confirms stored credentials exist and are valid via the local credentials manager.
Workspace & Resources
Confirms an active workspace is set, and reports CPU/RAM plus a recommended worker count for bulk conversion.
Conversion & Pipeline Errors
These are raised by the 5-phase conversion pipeline itself (discovery, planning, conversion, validation, auto-fix) when a specific phase can't complete.
"No conversion prompt for phase '{phase}'..." (PromptUnavailableError)
Conversion prompts and the knowledge base are never shipped locally: they're fetched from the 3XDE backend at run time, and both the live call and the encrypted local cache fallback failed. Run `3xcode login`, confirm you can reach the internet, and retry the conversion.
"Discovery failed for {file_name}" (DiscoveryError)
The discovery phase couldn't return a usable object inventory: the file may be malformed or truncated, or the model's response couldn't be parsed. Check that the input file isn't truncated or corrupted, then retry. If this happens across many files, run `3xcode health` to rule out a connectivity or model-availability issue.
"Phase {phase_name} timed out after {timeout}s" (ConverterTimeoutError)
The underlying AI call for that phase exceeded its timeout: usually a large or complex file, a slow model response, or network latency. Retry (most timeouts are transient); for consistently large files, consider splitting them into smaller SQL scripts before converting.
"Cannot connect to the AI runtime" (ConverterSDKError)
The connection to the AI runtime dropped before returning anything usable. Retry the conversion; if it persists, restart your terminal or the `3xcode ui` server, and re-run `3xcode login` in case it's an authentication issue.
"AI runtime process failed (exit {exit_code}): {stderr}" (ConverterSDKError)
The embedded stderr text carries the actual reason the process exited non-zero. Read it first; a common cause is an expired session, in which case re-running `3xcode login` resolves it.
Batches & Scheduling
A batch seems stuck with no progress
Run 3xcode batch watch <session_id> <batch_id> (or 3xcode session list-all) to confirm a worker is actually running. A single very large or complex file can legitimately take longer than the rest of the batch. If nothing is running, the batch is idle: resume it with 3xcode batch resume <session_id> <batch_id>, or 3xcode batch run if its pause window has expired.
`batch run` refuses with "a runner is already live for this batch"
Only one worker can run a given batch at a time, to avoid converting (and billing) the same files twice. Check what's already running with 3xcode batch watch <session_id> <batch_id>, or 3xcode batch cancel it first if it's actually stuck.
A batch scheduled with `batch schedule` never ran
This is an ordinary background process, not something registered with your OS: if the machine rebooted, slept in a way that killed background processes, or you logged out before the wake time, the scheduled run was lost. Re-schedule it, or use 3xcode schedule add instead if it needs to survive that.
A durable schedule (`schedule add`) never fired
Run 3xcode schedule status to confirm the OS-level tick is actually installed; if it shows not installed, run 3xcode schedule install once. If it is installed and a schedule still didn't fire, run 3xcode schedule run-due manually to dispatch immediately and see the error.
CLI, Auth & Workspace Errors
"No workspace found. Initialize one with: 3xcode workspace init <path> --name <name>" (WorkspaceNotFoundError)
The CLI tried to resolve a workspace root by walking up from your current directory and found none. Run `3xcode workspace init <path> --name <name>` in the project you're converting, or switch to an existing one with `3xcode workspace switch`.
License or login errors during `pyspark convert` / `pyspark analyze`
Both commands require an active workspace and a valid login before making any LLM call, since analysis is not a free/local operation. Run `3xcode login`, then `3xcode status` to confirm your license is valid and you have conversions remaining for the month.
Update Issues
`3xcode update` can't detect how the CLI was installed
This can happen in unusual environments (a custom virtualenv layout, an editable install). Fall back to the manual upgrade command for whichever tool you used: pip install --upgrade 3xcode-cli, uv tool upgrade 3xcode-cli, or pipx upgrade 3xcode-cli.
The update notice keeps appearing and you don't want it
Set THREEXCODE_DISABLE_UPDATE_CHECK=1 in your shell profile or CI environment. This silences the background update-check notice entirely rather than just delaying it. See Installation & Updates.
Web UI Issues
3xcode ui launches a local, single-user web server (default port 3210) for workspace, session, and bulk-conversion management. It mints a fresh session cookie every time it starts.
UI shows "Not logged in. Run 3xcode login in your terminal to get started."
The UI reads your locally stored credentials. It doesn't have its own separate login. Run `3xcode login` in a terminal, then reload the UI tab.
UI tab is stuck getting 403 errors on every API call after restarting `3xcode ui`
Each launch of `3xcode ui` mints a new session cookie. A browser tab left open across a restart can serve a stale cached page with the old cookie, so every API call 403s even though you're logged in via the CLI. Hard-refresh or close and reopen the UI tab after restarting the server.
Launching the UI
3xcode ui opens http://localhost:3210 in your browser automatically. Use --port to run on a different port if 3210 is already in use.