Troubleshooting

1. "configuration is required but not found"01

Cause:

• RequireConfig is enabled

• no extensions.database or database config key is present

Fix:

• add the config key in YAML

• or disable WithRequireConfig(true)

2. Startup fails with connection errors02

Cause:

• invalid DSN

• network/credential problems

• DB unavailable during eager open

Fix:

• validate DSN independently

• check credential secrets and network path

• tune MaxRetries, RetryDelay, ConnectionTimeout

3. "database not found" when resolving by name03

Cause:

• name mismatch between config and runtime lookup

Fix:

• use manager.List() to verify registered names

• keep a single name constant per database in your app code

4. Type mismatch when calling manager.SQL/Mongo/Redis04

Cause:

• requesting a database as wrong backend type

Fix:

• verify configured DatabaseType

• use correct accessor for that name

5. Transactions seem ignored05

Cause:

• repository still uses default *bun.DB instead of transaction-aware DB

Fix:

• inside transaction callback, always build repository with database.GetDB(txCtx, db)

6. Nested transaction behavior is unexpected06

Cause:

• inner transaction errors may be swallowed by callback logic

Fix:

• decide explicitly whether to propagate inner error

• remember nested flow is savepoint-based

7. Migration lock or status errors07

Cause:

• migration tables not initialized

• migration lock acquisition failed

Fix:

• call CreateTables/Init path before migrate/rollback/status

• verify migration table permissions

8. Slow query logs are too noisy08

Cause:

• low threshold or high traffic path

Fix:

• increase SlowQueryThreshold

• set DisableSlowQueryLogging if needed

• keep metrics enabled for observability without logs