Most Sqldelight errors become easier to solve when you identify which layer failed: Gradle configuration, SQL compilation, generated Kotlin code, runtime driver creation or schema migration. Fix the earliest error first because later messages may be consequences rather than separate problems.
The plugin cannot be resolved
Check the plugin id, requested version and repository configuration. Confirm that the version is compatible with the project’s Kotlin, Gradle and Java toolchain. Avoid changing several build components at once when diagnosing resolution failures.
No generated database class appears
Verify that the database configuration has a package name and that .sq files are located under the correct source set. Run the command-line build to separate IDE indexing problems from generation failures.
A query fails SQL compilation
Read the first reported line and confirm the selected dialect supports the syntax. Check table and column names, parameter nullability and result aliases. Reduce a complex statement until the failing expression is clear.
The runtime says no driver is available
Generated APIs do not include a database engine. Add the correct platform driver dependency, create the driver in platform code and pass it to the generated database constructor. Confirm that test and production source sets both receive the dependency.
A custom type has the wrong Kotlin value
Inspect the ColumnAdapter’s database type, encode path and decode path. Add a round-trip test and query the raw stored value when possible. Incorrect generic types can compile but still produce unexpected behavior.
Migrations are skipped or fail
Confirm file numbering, source location and the schema version used by the application. Test from an actual old database. A migration that works on an empty file may fail when rows violate a new constraint.
The IDE shows stale generated code
First run a normal Gradle sync and build. If the command-line build succeeds, refresh the project model. Delete generated output only as a last step, because repeated manual cleanup can hide a configuration problem.
Systematic debugging sequence
- Reproduce with a clean command-line build.
- Record the first error and affected file.
- Confirm plugin, runtime and driver versions.
- Reduce the SQL or configuration to a minimal case.
- Add a regression test before applying the final fix.