50-errors/README.md

Error Center & Troubleshooting

Status: 🟡 seeded (grows with each module) · Last validated: 2026-09-06

The consolidated error registry + symptom-first troubleshooting. This is what powers the portal's "describe the problem → get the trace" experience (see ../PORTAL_BUILD_PLAN.md).

Error IDs: <PREFIX>-E<NNN>, defined in each module/system page (section L). Prefixes are in

../STATUS.md.

Every error carries: message · technical cause · trigger · impact · detection (where to look) ·

resolution · tables to inspect · severity · related.

Consolidated error index (seeded)

ID	Area	Symptom	Inspect	Doc
AUTH-E001..006	Auth	login/OTP/lock/device/policy	`kv_auth_login_attempts`, `notification_otp_codes`, `kv_auth_sessions`	auth
WAL-E001..005	Wallet	insufficient/signature/wrong-wallet/orphan/booked-as-revenue	`wallet_accounts`, `wallet_transactions`, `accounting_journal`	wallet
FIN-E001..004	Commission	fee 0 / wrong module / stuck pending / settlement % 0	`kv_commission_rules`, `commission_transactions`, `commerce_settlement_settings`	commission
MEM-E001..003	Membership	price 0 / priced-but-0-sold / no renewal	`kv_membership_plan_prices`, `kv_memberships`	membership
KYC-E001..003	KYC	OTP / cannot publish / no verification product	`claim_kyc_requests`, `verification_plans`	kyc-trust
COM-E001..003	CommerceX	price 0 / unavailable / quick unresolvable	`products_master`, `product_variants`, `commerce_order_routing`	ecommerce flow
FOOD/STAY/EVT-E	Food/Hotel/Events	header/child count mismatch	`food_orders`/`hotel_bookings`/`events_master` vs child tables	module pages
RIDE-E002	RideMate	ride commission not in ledger	`commission_transactions` (0 for rides)	ridemate
RLTY-E001..003	RealEstate	role gate / empty perf screen / stuck commission	`company_business_profiles` (0 realestate)	realestate
DIR-E001..002	Directory	claim not converting / page unreachable	`entity_listing_claims` (0)	directory
NOTF-E001..003	Notifications	email/push/WhatsApp not delivered	`email_queue`, `push_subscriptions`, `wa_optins`	notifications
UE-E001..002	Universal Entry	no match / stale supply	`kv_ue_capability_registry`, `kv_ue_supply`	search-radar
ENG-E001..002	Engines	compare empty / negotiation unused	`kv_compare_offers`, `negotiations`	platform-engines
ADM-E001..002	Admin	accounting hidden / DDL no-op	nav_registry, migration system	admin

Symptom-first troubleshooting

"Why is a payment / order showing pending?"

Which module? Order ids collide — identify module_key + order table first.
Check the module order row payment_status (e.g. orders_master.payment_status).
Check the wallet debit: wallet_transactions for the buyer around that time — did debit()

succeed? (WAL-E001 insufficient balance leaves the order unpaid.)

Check the central ledger: kv_order_finance_master by (module_key, order_table, order_id) —

status and paid_amount vs gross_amount.

For gateway topups: confirmCreditsPurchase signature failure (WAL-E002) means no credit was

written → wallet still short → order pending.

Real-estate specific: commission may be pending forever (FIN-E003) even when the order is paid.

→ See wallet, central ledger.

"Why can't a merchant publish a product / listing?"

Walk the gate chain (any break stops publishing):

Module on? kv_module_control.<module>.master_status = 1.
Enrolled? a kv_module_registry type + a company_master row + a company_business_profiles

row for that module_key (RealEstate's blocker: 0 realestate rows → RLTY-E001).

Membership? active kv_memberships tier if the feature is gated.
KYC approved? an approved claim_kyc_requests row (KYC-E002).
Validation — required fields/media pass; media moderation (post_media_moderation) not blocking.

→ See kyc-trust, membership, module-registry.

"Why is a fee / commission 0?"

kv_commission_rules is empty → rule-matrix fees (pay-per-lead, per-application) default to 0 (FIN-E001). Base per-order commission still fires via platform_commission_settings (11 rows, all 5.00% as of 2026-09-06). Settlement-layer commission is a separate question: commerce_settlement_settings has 0 rows, so CommerceSettlementModule always resolves that figure to 0% (FIN-E004) — a 5% order commission and a 0% settlement commission on the same order are both correct/expected given current config, not a bug by themselves. → commission.

"Why is a wallet-funded escrow/refund/transfer showing up as platform revenue?"

WalletModule::journalAccountsFor() defaults un-tagged movements to REVENUE_GENERAL when the caller didn't pass meta['acct_purpose'] — confirmed on 41% of accounting_journal rows (2026-09-06) (WAL-E005). Cross-check wallet_transactions.type/meta_source for the real nature of the movement before trusting accounting_journal.credit_account. → wallet, central ledger.

"Why does a table look empty but the feature worked?"

Two causes: (a) large text offloaded to kv_payload_store (hydrate on read); (b) a header table purged while child/finance rows remain (Food/Hotel/Events show this). → database.

How to extend

When documenting a module, add its <PREFIX>-E<NNN> errors to the module page (section L) and a row here. Phase 2 of the portal ingests these into kvdoc_error for structured search.