When something goes wrong
At the end of this page, you can read a SQLSRC build error, find its fix, and fix an exception at run time.
Read an SQLSRC error
This is one error line of dotnet build:
/work/App/Queries/UserRepository.sql(1,10): error SQLSRC241: The query 'GetUser' has no entry in the sidecar of its file, and its output 'repository' needs one. Run 'sqlsource describe'. (https://mbcrawfo.github.io/SqlSource/diagnostics.html#sqlsrc241) [/work/App/App.csproj]
Queries/UserRepository.sql(1,10)is the file, the line and the column. An error about a query is at the query's name.SQLSRC241is the id of the error.- The message says what is wrong, and often what to run.
- The link opens the section of the error in the list of errors, which says why it happens and how to fix it.
- The project file in brackets is the project that the build was building.
An error of the build that has no file, such as one about a package version, starts with CSC in place of the file.
What an error costs you
- An error in how a
.sqlfile is written costs the whole file its code. No query of the file gets its models or its method until you fix it. - An error about describing a query costs that query its models and its method. The other queries of the file keep theirs.
- A query that your database rejects holds back each other new or changed query of its file, with SQLSRC241 or SQLSRC244. Fix the query, and the others are described too.
The errors you meet first
- SQLSRC241: the query has no entry in the sidecar. Describe it: build with your
.envfile in place, or rundotnet sqlsource describe. Then commit the sidecar. - SQLSRC244: the entry is stale, since the query changed after it was described. Describe it again, as for SQLSRC241.
- SQLSRC209: the query needs a dialect that can be described. Name your database in
sqlsource.json, as Your first query shows. - SQLSRC213: your database has no connection. Put the
.envfile in the folder of your project, not at the root of your repository. - SQLSRC220: the project was not restored. Run
dotnet restore. Then run the tool again. - SQLSRC224: your database could not be opened. Check that it runs. Check the connection string and the password. For SQL Server in a local container, add
TrustServerCertificate=True. - SQLSRC226 and SQLSRC227: the type of a parameter could not be determined, or its first use does not fix it. Add a
-- param:line with the type, such as-- param: @name text null. - SQLSRC021: the compiler is too old. Update the .NET SDK to 9.0.300 or later, or Visual Studio to 2022 17.14 or later.
- SQLSRC267: Microsoft.Data.SqlClient is older than 6.1, often because EF Core 8 or 9 brings 5.1. Reference Microsoft.Data.SqlClient 6.1 or later in your project file.
- SQLSRC206: the project manifest cannot be read, because the tool and the
SqlSourcepackage have different versions. Update the older one.
It built, but it fails when it runs
Some problems show only when a method runs, such as an InvalidCastException, or a null in a column that you marked never null. Troubleshooting lists them by what you see, each with its fix.
What you have now
A way to read any SQLSRC error, and the fixes of the errors you meet first.
Rules: where an error is reported, what an error costs, running in the build, the list of errors.
Next: What do you want to do?