Troubleshooting¶

Solutions to common configuration issues.

New projects should declare fields on a DbwardenDatabase subclass. The database_config(...) function alternative is also supported.

"No configuration found"¶

Symptom¶

ConfigurationError: No configuration found

Causes & Solutions¶

Cause 1: No dbwarden.py file

# Check if file exists
ls dbwarden.py

Solution: Create dbwarden.py:

$ dbwarden init

Cause 2: Wrong directory

dbwarden looks in current directory and parents.

Solution: Navigate to project root:

cd /path/to/project
$ dbwarden migrate

Cause 3: No database configuration

Solution: Add configuration:

# dbwarden.py
from dbwarden import DbwardenDatabase

class Primary(DbwardenDatabase):
    database_name = "primary"
    default = True
    database_type = "sqlite"
    database_url_sync = "sqlite:///./app.db"

Cause 4: Import error in config file

# dbwarden.py
from app.models import Base  #  Import fails

Solution: Fix imports or use lazy loading:

# Don't import models in config file
primary = database_config(
    database_name="primary",
    model_paths=["app.models"],  #  Use model_paths instead
)

"Exactly one default=True required"¶

Symptom¶

ConfigurationError: Exactly one default=True required

Causes & Solutions¶

Cause 1: No default database

#  Wrong
analytics = database_config(
    database_name="analytics",
    default=False,
)

Solution: Set one database as default:

#  Correct
analytics = database_config(
    database_name="analytics",
    default=True,
)

Cause 2: Multiple defaults

#  Wrong
analytics = database_config(
    database_name="analytics",
    default=True,
)

Solution: Only one default:

#  Correct
analytics = database_config(
    database_name="analytics",  # default=False implied
)

"Duplicate database_name"¶

Symptom¶

ConfigurationError: Duplicate database_name 'primary'

Cause¶

Same database_name used twice:

primary = database_config(
    database_name="primary",  #  Duplicate
)

Solution¶

Use unique names:

analytics = database_config(
    database_name="analytics",  #  Different name
)

"No SQLAlchemy models found"¶

Symptom¶

Warning: No SQLAlchemy models found

Causes & Solutions¶

Cause 1: Wrong model_paths

#  Wrong
model_paths=["models"]  # Not on PYTHONPATH

Solution: Use correct Python path:

#  Correct
model_paths=["app.models"]

Cause 2: Models not imported

# app/models/__init__.py
#  Wrong - models not imported
from sqlalchemy.orm import DeclarativeBase

class Base(DeclarativeBase):
    pass

Solution: Import models:

# app/models/__init__.py
#  Correct
from sqlalchemy.orm import DeclarativeBase
from app.models.user import User
from app.models.order import Order

class Base(DeclarativeBase):
    pass

Cause 3: Missing model_paths

Solution: Add model_paths:

primary = database_config(
    database_name="primary",
    model_paths=["app.models"],  #  Add this
)

Cause 4: Circular imports

# app/models/user.py
from app.models.order import Order  #  Circular

# app/models/order.py
from app.models.user import User  #  Circular

Solution: Use TYPE_CHECKING:

from typing import TYPE_CHECKING

if TYPE_CHECKING:
    from app.models.order import Order

"model_paths is required"¶

Symptom¶

ConfigurationError: model_paths is required when more than one database is configured

Cause¶

Multiple databases without model_paths:

#  Wrong
analytics = database_config(
    database_name="analytics",  # No model_paths
)

Solution¶

Add model_paths to all databases:

#  Correct
primary = database_config(
    database_name="primary",
    model_paths=["app.models.primary"],
)
analytics = database_config(
    database_name="analytics",
    model_paths=["app.models.analytics"],
)

"model_paths overlap detected"¶

Symptom¶

ConfigurationError: model_paths overlap detected: path 'app.models' from 'analytics' is also defined in 'primary'; set overlap_models=True to allow

Cause¶

Same model paths for different databases:

#  Wrong
primary = database_config(
    database_name="primary",
    model_paths=["app.models"],
)
analytics = database_config(
    database_name="analytics",
    model_paths=["app.models"],  #  Same path
)

Solutions¶

Solution 1: Use separate paths

#  Correct
primary = database_config(
    database_name="primary",
    model_paths=["app.models.primary"],
)
analytics = database_config(
    database_name="analytics",
    model_paths=["app.models.analytics"],
)

Solution 2: Allow overlap (if intentional)

#  Correct for read replicas
primary = database_config(
    database_name="primary",
    model_paths=["app.models"],
    overlap_models=True,
)
replica = database_config(
    database_name="replica",
    model_paths=["app.models"],
    overlap_models=True,
)

"model_tables overlap detected"¶

Symptom¶

ConfigurationError: model_tables overlap detected: table 'users' in 'primary' is also in 'analytics'

Cause¶

Two databases have model_tables lists that share table names:

#  Wrong
primary = database_config(
    database_name="primary",
    model_paths=["app.models"],
    model_tables=["users", "posts"],
)
analytics = database_config(
    database_name="analytics",
    model_paths=["other_models"],
    model_tables=["users"],  # 'users' already owned by primary
)

Solutions¶

Solution 1: Remove duplicate table name

#  Correct
analytics = database_config(
    database_name="analytics",
    model_paths=["other_models"],
    model_tables=["analytics_events"],  # No overlap with primary
)

Solution 2: Allow overlap (if intentional)

#  Correct for shared tables
analytics = database_config(
    database_name="analytics",
    model_paths=["other_models"],
    model_tables=["users", "analytics_events"],
    overlap_models=True,  # Allow overlap
)

"dev_database_url is required"¶

Symptom¶

ConfigurationError: dev_database_url is required when dev_database_type is set

Cause¶

Set dev_database_type without dev_database_url:

#  Wrong
primary = database_config(
    database_name="primary",
    dev_database_type="sqlite",
    # Missing dev_database_url
)

Solution¶

Add both dev parameters:

#  Correct
primary = database_config(
    database_name="primary",
    dev_database_type="sqlite",
    dev_database_url="sqlite:///./dev.db",  #  Add this
)

Connection Errors¶

"could not connect to server"¶

Cause: Database server not running or unreachable.

Solutions:

Check database is running:

# PostgreSQL
sudo systemctl status postgresql

# Docker
docker ps | grep postgres

Check connection URL:

# Verify host, port, credentials
database_url_sync="postgresql://user:pass@localhost:5432/myapp"

Test connection:

# PostgreSQL
psql -h localhost -U user -d myapp

# MySQL
mysql -h localhost -u user -p myapp

"authentication failed"¶

Cause: Wrong credentials.

Solutions:

Check credentials:

# PostgreSQL
psql -h localhost -U user -d myapp

Verify environment variable:

echo $DATABASE_URL

URL encode special characters:

from urllib.parse import quote_plus

password = "p@ss:word"
encoded = quote_plus(password)  # "p%40ss%3Aword"

"database does not exist"¶

Cause: Database not created.

Solution: Create database:

-- PostgreSQL
CREATE DATABASE myapp;

-- MySQL
CREATE DATABASE myapp CHARACTER SET utf8mb4;

Import Errors¶

"ModuleNotFoundError"¶

Cause: Python can't find module.

Solutions:

Check PYTHONPATH:

export PYTHONPATH=/path/to/project:$PYTHONPATH

Install package:

uv add -e .  # Editable install

Verify import:

python -c "import app.models"

Performance Issues¶

Slow configuration loading¶

Cause: Large codebase scan.

Solution: Specify model_paths:

#  Slow - scans everything
primary = database_config(
    database_name="primary",
)

#  Fast - targeted scan
primary = database_config(
    database_name="primary",
    model_paths=["app.models"],
)

Slow imports¶

Cause: Heavy imports in config file.

Solution: Avoid imports in dbwarden.py:

#  Slow
from app.models import Base
from app.services import setup

#  Fast
from dbwarden import DbwardenDatabase

class Primary(DbwardenDatabase):
    ...

Debugging Tips¶

Enable verbose output¶

$ dbwarden migrate --verbose

Check configuration¶

# Show all configuration
$ dbwarden settings show

# Show specific database
$ dbwarden settings show primary

Test imports¶

python -c "import dbwarden; print('OK')"
python -c "from dbwarden import database_config; print('OK')"

Verify database connection¶

$ dbwarden check-db
$ dbwarden check-db --database primary

What's Next?¶

Configuration API Reference - Complete parameter docs
Quick Start - Start fresh with correct setup
CLI option inventory - Every built-in flag, including --disable-skip

Exit code 3¶

Exit code 3 can report a skipped database or a safety ceiling stop; inspect the accompanying result before treating it as success. See safety-scoped migrations for the severity ceiling semantics.