3XDE Documentation

Troubleshooting

Real error messages the 3XCode CLI can surface, what causes them, and how to resolve each one.

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: the Claude Code CLI binary, the 3XDE backend connection, your stored credentials, an active workspace, and available system resources.

Terminal

3xcode health

3XCode CLI

Confirms the claude binary is on PATH, since it powers the underlying AI engine that every conversion phase runs on.

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.

"Claude Code CLI not found." (ConverterSDKError)

The Claude Code CLI binary that the conversion engine shells out to isn't installed or isn't on PATH. Run the install command shown in the error (`curl -fsSL https://claude.ai/install.sh | bash`), then restart your conversion or `3xcode ui`.

"Cannot connect to Claude Code CLI: {exc}" (ConverterSDKError)

The subprocess connection to the Claude CLI dropped before returning anything usable. Retry the conversion; if it persists, check whether another process is holding the CLI, restart your terminal (or the `3xcode ui` server), and verify the CLI isn't crashing on launch.

"Claude process failed (exit {exit_code}): {stderr}" (ConverterSDKError)

The Claude CLI subprocess exited non-zero: the embedded stderr text carries the actual reason. Read it first; a common cause is an expired or invalid session, in which case re-running `3xcode login` resolves it.

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.

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.

PreviousFAQ NextSupport Hub