Troubleshooting

Start with the project health check:

RUST_LOG=rent=debug rent doctor

The generated client is stale

Run rent generate. Client crates created by rent new or rent init --crate have a build script that compares the RSL schema fingerprint during cargo check and cargo run, so a stale client fails early with an explicit "run rent generate" instruction. rent init inside an existing package does not replace or create the package's build script. For that layout, use rent doctor to check freshness and rent dev to regenerate while editing. Generation reads the schema configured in rent.toml: either a single RSL file or a directory of RSL files. 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

Check the connection URL selected by url_env in rent.toml (DATABASE_URL by default). Rent reads it from the process environment or the project's .env. An exported value takes precedence over .env. Its scheme should match the configured database.

rent doctor

For a local or hosted server, check the hostname, port, credentials, TLS settings, and any required VPN or network access. Confirm that the server is running and accepts connections from the machine running your command.

If you chose the scaffold's optional Docker Compose setup, start those local containers with:

docker compose up -d --wait

Docker is not required by Rent. The same connection checks apply to an existing database server or a managed database service.

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 recording it with migrate resolve.
• 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.