Xuda logo

xuda.io

Technical docs for Xuda Slim and Xuda CLI

Product overview
Troubleshooting

Internal and undeclared errors

Errors that bypass the { code, data } envelope or have no catalog entry yet. They are detected by shape or source rather than by a fixed number.

Troubleshooting pages

CPI server error codes, the HTTP mapping, and how to resolve each one.

Docs page

Errors that bypass the { code, data } envelope or have no catalog entry yet. They are detected by shape or source rather than by a fixed number.

uncaught_exception Uncaught exception

Severity: error · Category: process · Detected via: process.on('uncaughtException')

A thrown error that was not wrapped in the { code, data } envelope.

Common causes

  • Bug throwing outside a try/catch
  • Unexpected runtime fault

Resolution

  1. Resolver reports it (report-only); existing crash behavior preserved
  2. Escalate to ops

Auto-fix: none · User-actionable: no · Related: unhandled_rejection

Source: process-level detector (2e)

unhandled_rejection Unhandled promise rejection

Severity: error · Category: process · Detected via: process.on('unhandledRejection')

A rejected promise that nobody caught.

Common causes

  • Missing await/catch on an async call

Resolution

  1. Resolver reports it (report-only)
  2. Escalate to ops

Auto-fix: none · User-actionable: no · Related: uncaught_exception

Source: process-level detector (2e)

thrown_string_error Thrown string error

Severity: error · Category: envelope-bypass · Detected via: router global catch ~2075

A throw new Error(...) that surfaces as a 401/500 instead of a { code, data } body.

Common causes

  • e.g. 'app is off', 'Account suspended', 'Account terminated' (router ~3400-3409)

Resolution

  1. Resolver triages from the message
  2. Escalate or notify per diagnosis

Auto-fix: none · User-actionable: no · Related: 401, 500

Source: router_module ~3400-3409

broker_failure Message broker failure

Severity: error · Category: broker · Detected via: ms_broker.mjs / msg_broker.mjs error paths

RabbitMQ disconnect, queue timeout, or message serialization error.

Common causes

  • Broker down/unreachable
  • Queue timeout
  • Serialization error

Resolution

  1. Resolver reports it
  2. Check RabbitMQ health
  3. Escalate to ops

Auto-fix: none · User-actionable: no · Related: provider_outage

Source: common/ms_broker.mjs, common/msg_broker.mjs

unknown_code Unknown negative code

Severity: warning · Category: catalog-gap · Detected via: resolver lookup miss

A negative code with no catalog entry (new code shipped since the last catalog update).

Common causes

  • New code added in a module but not yet documented here

Resolution

  1. Resolver writes a catalog_gap proposal for human review
  2. Add the code to this catalog

Auto-fix: none · User-actionable: no

Source: resolver (2e)

malformed_response Malformed response

Severity: error · Category: envelope-bypass · Detected via: resolver shape check

A response missing/zero code, non-object, or null data where data was expected.

Common causes

  • Method returned the wrong shape
  • Partial/short-circuited return

Resolution

  1. Resolver triages
  2. Fix the offending method to return { code, data }

Auto-fix: none · User-actionable: no

Source: resolver (2e)

provider_outage Upstream provider outage

Severity: error · Category: dependency · Detected via: ai_module report_ai_status error; DB connect failures

An external dependency (AI, DB, upstream service) is unavailable.

Common causes

  • OpenAI/AI provider error
  • CouchDB connect failure
  • Upstream down

Resolution

  1. Resolver may retry transient ops
  2. Escalate if sustained

Auto-fix: retry · User-actionable: no · Related: -999, 502

Source: resolver (2e)

anomaly Error-rate anomaly

Severity: warning · Category: aggregate · Detected via: cron sweep aggregation (anomaly_threshold)

A signature repeats above threshold in the window, even with no single fatal error.

Common causes

  • Spike of the same error signature

Resolution

  1. Resolver clusters and escalates the pattern to ops

Auto-fix: none · User-actionable: no

Source: resolver sweep (2e)