Troubleshooting

Start with the project health check:

RUST_LOG=rent=debug rent doctor

The generated client is stale

Run rent generate. Generated projects compare the RSL schema fingerprint during cargo check and cargo run, so a stale client fails early with an explicit "run rent generate" instruction. Generation reads rent/schema.rsl; editing a generated file is never the fix because the next generation replaces Rent-owned files. rent dev is available during active schema work.

If a generated model refers to a disabled database type, ensure database.backends in rent.toml matches Rent's Cargo features, then regenerate.

The database cannot be reached

Confirm DATABASE_URL exists in the command's environment and that its scheme matches the configured dialect. For a scaffolded server project, run:

docker compose up -d --wait
rent doctor

A pool acquisition timeout usually means the database is unavailable, every connection is busy, or the process pool budget is too small. Inspect database connection counts before increasing it.

A migration is blocked

rent migrate validate
rent migrate status
rent migrate preflight

• A checksum mismatch means an applied migration file changed. Restore it and add a new migration.
• A dirty migration means execution failed after it began. Inspect the database before using migrate repair.
• A destructive classification requires explicit review and approval; it is not bypassed silently.
• Drift means the live catalog and RSL schema differ independently of the migration journal.

NotFound or NotSingular

only() requires exactly one row. Use only_or_none() when absence is expected, or make the filter unique when multiple rows are possible. Treat NotSingular as a query/schema invariant failure rather than arbitrarily choosing a row.

An optimistic update was rejected

EntityError::OptimisticLock means another writer changed the row after it was read. Reload the entity, reapply the user's intent, and retry only when that merge is valid for the application.

A transaction closed unexpectedly

Do not retain or spawn work with a transaction client after its closure returns. A closure transaction commits only when the closure returns Ok; any error triggers rollback. Use savepoints for partial rollback inside one transaction instead of starting a nested transaction.

An extension check is blocked

rent extension check reports missing installation files, preload libraries, privileges, incompatible versions, and provider control-plane requirements. Satisfy the server prerequisite first; changing the Rust pack does not install server binaries.

For structured diagnostics, add --format json to migration and extension commands where supported.