Troubleshooting

Start with the errcode in the response or log. It names the failing layer more precisely than the HTTP status.

Startup

Symptom	Cause	Fix
Exits with CFG-14x / CFG-15x	A secure-defaults check failed	Fix the named setting. Use RIVERBASE_INSECURE_ALLOW only in throwaway environments.
Exits with CAS-012 / CAS-013	Casbin policy and mounted commands disagree	Add the missing rows, or remove stale ones
mount_auth_routes fails	Provider is None without RIVERBASE_AUTH_DISABLED=1	Configure a provider, or disable auth explicitly
Sort coverage error at spawn	A sortable query field has no order entry on the entity	Add it to pg_domain_entity! order, or mark the field no_sort
policy: public requires a reason and sign-off	A compile error from query_resource!	Use policy: public("why", "TICKET")
Migration errors	Wrong RIVERBASE_DB_URL, or a missing database	Check the DSN; create the database

Requests

Symptom	Cause	Fix
401 AUT-001	No or invalid credentials	Send Authorization; check the token issuer and audience
400 AUT-172	Bearer sent while MockAuth is active	Use a MockAuth- header locally
403 AUT-003	Casbin denied the activity	Policy rows must use {cmdkey}.execute / {resource}.query
403 CAS-011	A custom route has no activity mapping	Register it as enforced with policy, or as public with a reason
404 on a custom route	Mounted with mount_coupled, or into_arc() skipped	Use spawn(..).await?.into_arc() and mount_domain
404 DAT-001 on :exec	Row missing, or in another tenant	Check _tenant and the caller's profile
409 DAT-090	Unique violation	Handle it in the domain, or check for existence first
422 WEB-001	Payload did not match the command's type	Compare with GET …/{cmdkey}.meta
500 DOM-016	A state write outside #[domain_action]	Move the write into an action method
An empty list where rows exist	The tenant filter or scope_policy excluded them	Check the active profile (X-Profile) and the policy expression
WEB-103	Body larger than request_body_max_bytes	Raise the limit, or upload with multipart

Data and messaging

Symptom	Cause	Fix
relation "…" does not exist	Domain migrations not applied	Run --migrate-only; check with_migrate in the store spec
Command rows stuck in Created	The process died mid-command	Nothing committed; safe to retry with the same idempotency key
Consumers see duplicates	At-least-once outbox delivery	Make consumers idempotent by message id
Realtime clients miss updates across replicas	No shared StreamBus	Use NATS, Redis, or Postgres for [riverbase.bus]
CMD-027	The store claimed transactions but returned a non-transactional unit	Fix the custom DataStore, or set supports_command_transactions to false

Macros

Symptom	Fix
Opaque type errors at a command_engine! call	cargo expand -p <crate> command and read the generated code
unknown domain_trait	Use generate or manual
#[domain_action] cannot find core	Name the aggregate's field core