Error Codes

Every user-facing error from bext has a stable code following the E__ 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, or info

- Explanation — multi-sentence prose

- Examples — concrete triggers

- Next steps — numbered, actionable

- See also — related error codes