Error Codes
Every user-facing error from bext has a stable code following the E_<AREA>_<WHAT> pattern. Use bext explain <code> to get full prose, examples, and next steps from the terminal.
Quick Reference#
Config#
| Code | Title |
|---|---|
E_CONFIG_PARSE |
Configuration file failed to parse |
E_CONFIG_UNKNOWN_SECTION |
Unknown top-level section in config |
E_CONFIG_UNKNOWN_KEY |
Unknown key inside a known section |
E_CONFIG_DEPRECATED_KEY |
Deprecated configuration key |
Plugin#
| Code | Title |
|---|---|
E_PLUGIN_SCAN_BLOCKED |
Plugin directory scan blocked |
E_PLUGIN_LOAD_FAILED |
Plugin failed to load |
E_PLUGIN_MANIFEST_INVALID |
Plugin manifest is invalid |
Build#
| Code | Title |
|---|---|
E_BUILD_BUNDLE_FAILED |
SSR bundle build failed |
E_BUILD_TIMEOUT |
Build timed out |
Render#
| Code | Title |
|---|---|
E_RENDER_SSR_PANIC |
SSR render panicked |
E_RENDER_TIMEOUT |
SSR render timed out |
E_RENDER_DEADLINE |
Render deadline exceeded (soft) |
Cache#
| Code | Title |
|---|---|
E_CACHE_REDIS_DOWN |
Redis cache backend unreachable |
E_CACHE_STAMPEDE |
Cache stampede detected |
TLS#
| Code | Title |
|---|---|
E_TLS_ACME_FAILED |
ACME certificate provisioning failed |
E_TLS_CERT_EXPIRED |
TLS certificate has expired |
WAF#
| Code | Title |
|---|---|
E_WAF_RULE_BLOCKED |
Request blocked by WAF rule |
E_WAF_RATE_LIMITED |
Request rate-limited |
Proxy#
| Code | Title |
|---|---|
E_PROXY_UPSTREAM_DOWN |
Upstream server is unreachable |
E_PROXY_TIMEOUT |
Upstream request timed out |
Auth#
| Code | Title |
|---|---|
E_AUTH_TOKEN_INVALID |
Authentication token is invalid |
E_AUTH_TOKEN_EXPIRED |
Authentication token has expired |
Runtime#
| Code | Title |
|---|---|
E_RUNTIME_PORT_IN_USE |
Listen port is already in use |
E_RUNTIME_STARTUP_FAILED |
Server startup failed |
Deploy & Upgrade#
| Code | Title |
|---|---|
E_DEPLOY_HEALTH_GATE_FAILED |
Post-deploy health gate failed |
E_UPGRADE_ROLLBACK |
Upgrade rolled back |
Secrets#
| Code | Title |
|---|---|
E_SECRETS_STORE_LOCKED |
Secret store is locked |
Network#
| Code | Title |
|---|---|
E_NETWORK_DNS_FAILED |
DNS resolution failed |
Using Error Codes#
From the terminal#
bext explain E_CONFIG_PARSE
Output includes: explanation, concrete examples that trigger the error, numbered next steps, and cross-references to related codes.
In CI#
bext explain E_CONFIG_PARSE --json
Returns a JSON object with code, title, area, severity, explanation, examples, next_steps, and see_also fields.
Listing all codes#
bext explain # Human-readable table
bext explain --json # Full JSON registry
Fuzzy matching#
If you mistype a code, bext suggests the nearest match:
bext explain E_CONFIG_PARS
# unknown error code `E_CONFIG_PARS`. Did you mean:
# E_CONFIG_PARSE Configuration file failed to parse
How Codes Are Structured#
E_CONFIG_PARSE
│ │ │
│ │ └── What happened (PARSE, UNKNOWN_SECTION, TIMEOUT, …)
│ └── Area of the system (CONFIG, PLUGIN, BUILD, RENDER, …)
└── Error prefix (always E_)
Every entry in the registry includes:
- Severity —
fatal,error,warning, orinfo - Explanation — multi-sentence prose
- Examples — concrete triggers
- Next steps — numbered, actionable
- See also — related error codes
Tip
Run bext explain <code> --json in CI to get machine-readable output including next_steps as an array. This is useful for automating triage or surfacing actionable hints in your deployment pipeline.
Related#
- Troubleshooting — per-symptom diagnosis and fix commands
- Logging — error codes appear in the
level: "error"log stream - Monitoring — alerting rules keyed on
http_requests_total{status=~"5.."} - Zero-Downtime Upgrades —
E_UPGRADE_ROLLBACKand deploy error codes - Configuration: bext.config.toml —
E_CONFIG_*codes reference the sections described here