Table of Contents

How errors are reported

This page tells you how SqlSource reports a problem: how severe it is, where you see it, what it costs and what reports it. Each error, with its cause and its fix, is on the page Diagnostics.

Errors, warnings and information

Every problem that SqlSource finds is an error. You cannot turn an error off or make it a warning. Eight ids are the exceptions.

These six are warnings:

  • SQLSRC026: the build cannot start the sqlsource tool, and goes on with the sidecars it has.
  • SQLSRC031: a connection is marked for a logical database that no repository query uses.
  • SQLSRC121: a parameter of a SQL Server query is written in two spellings.
  • SQLSRC240: another version of the tool wrote a sidecar, or an entry of one.
  • SQLSRC245: an entry of a sidecar names no query that needs it.
  • SQLSRC284: a short name of a C# type that you chose finds a type of a package that the project does not reference itself.

These two are information, about the version of a database driver:

The section of each of the eight says how a project can configure it.

Information is not in the output of dotnet build. An IDE that lists information shows it, and the build log has it at the detailed verbosity, as SQLSRC248 says.

Where an error is reported

The build reports its errors and warnings in its output, and your IDE lists them with the compiler's. Each one names the file, the line and the column of the problem, where it has them:

  • A .sql file. An error in a .sql file is at its line and column in that file. An error about a query is at the query's name, or at the marker that the error is about.
  • A sidecar. An error in a sidecar is at its line and column in the sidecar.
  • A settings file. An error in a settings file, sqlsource.json, is at its line and column in that file.
  • A C# file. An error about a type that carries [SqlSourceGenerate] is at the type's name, at its attribute, or at the member that the error names.
  • The project file. The errors of a build that runs the tool, SQLSRC024 to SQLSRC027, are at the project file.

Some errors are about the project's references, and have no file and line. In the build's output, such an error starts with CSC in place of a path. These are reported once for the project:

Two more have no file and line, and the project can get more than one of each:

  • SQLSRC273, a driver that the project does not reference, is reported once for each driver that is missing, Npgsql or Microsoft.Data.SqlClient.
  • SQLSRC282, a library that is too old, is reported once for each package that is too old.

SQLSRC021, a compiler that is too old, comes before the build compiles anything.

What an error costs

Most errors cost part of what SqlSource generates, until you fix them. What an error costs depends on what it is about.

  • How a .sql file is written. An error from SQLSRC101 to SQLSRC120, or SQLSRC126, costs the file all its members and models. The other files of the type keep theirs. The section of SQLSRC120 says when it costs only a type that keeps comments.
  • Where a query's members go. An error from SQLSRC122 to SQLSRC125 costs the file its members and models for the type that the error is reported for. Another type that claims the file keeps them. The section of SQLSRC123 says when it costs one method alone.
  • An empty list. SQLSRC127 is reported only for a query whose output is repository or methods. It costs that query its method, and nothing else.
  • Describing a query, or its sidecar. An error such as SQLSRC241 costs the query that it is about its models. SQLSRC209 costs its models to each query of the file that needs an entry. The other members of the file stay in place.
  • A repository. Each of SQLSRC028 to SQLSRC034, and SQLSRC036, costs a method to each repository query of the logical databases that it is about. The warning SQLSRC031 is not one of them. The models of those queries are still generated.

A query can get several errors at once. If a query has an error about describing it, its sidecar, its models or its method, the query's output decides what it keeps:

  • If the output is models, the query keeps its constant or its token method.
  • If the output is repository or methods, the query gets no method until you fix every error.

The section of an error says when it costs less. SQLSRC297 costs only the collection method, SQLSRC299 only the synchronous methods, and SQLSRC281 costs nothing.

While a .sql file has an error of its own, the build checks less of its sidecar: see sidecar files.

Who reports an error: the build, the tool, or both

Two things report errors: the build of your project, and the sqlsource tool, such as dotnet sqlsource describe. Each section of Diagnostics has a line under its title that says which one reports its error.

Reported by Ids What you see
The build alone SQLSRC001 to SQLSRC013, SQLSRC020 to SQLSRC038, SQLSRC121 to SQLSRC125, SQLSRC127, SQLSRC237 to SQLSRC261, SQLSRC267 to SQLSRC270, SQLSRC272 to SQLSRC284, and SQLSRC297 to SQLSRC299 The build reports them, and the tool never does. SQLSRC020, a key that a settings file repeats, is the build's alone. SQLSRC122 to SQLSRC125 depend on the type that claims the file, and SQLSRC127 on the query's output
The tool alone SQLSRC200 to SQLSRC208, SQLSRC211 to SQLSRC236, SQLSRC262 to SQLSRC266, SQLSRC271, and SQLSRC285 to SQLSRC296 The tool reports them. A build shows them only when it runs the tool, as running in the build says
The build and the tool: how a .sql file is written SQLSRC101 to SQLSRC120, and SQLSRC126 The tool reports them with the same id as the build. The problem is the same, and so is the fix
The build and the tool: a settings file SQLSRC015 to SQLSRC019 The tool reports them at the same line and column as the build. It reports them only for a settings file that applies to a .sql file or a C# file of a project it runs on. It reports each once in a run, however many of those projects the file applies to. The tool reports SQLSRC019 for dialect, output and database alone. The build reports it for every key but database, whose value the tool alone checks
The build and the tool: a query that cannot be described SQLSRC209 and SQLSRC210 Each reports them at the same place: the query that must be described and cannot be

In a build that runs the tool, the build lists each error that both report once: see running in the build.

The tool's errors

$ dotnet sqlsource describe --check
/work/App/Queries/Users.sql(3,10): error SQLSRC219: The sidecar is out of date for 'GetUser': the query has changed since it was described
    help: run 'dotnet sqlsource describe' and commit the sidecars
    see: https://mbcrawfo.github.io/SqlSource/diagnostics.html#sqlsrc219

The tool prints its errors itself, in your terminal. Each error has the format of a build error: its place, error, the id and the message. The place is the file, with the line and column when the error has them. An error with no file starts with sqlsource in place of a path.

Lines under the error tell you more. A help: line, when the error has one, says what to do. The last line, see:, links to the error's section of Diagnostics.

The tool's exit code says whether it reported an error: see exit codes. In a build that runs the tool, each of its errors is an error of the build: see running in the build.

Errors by area

Ids below 100 are about the type that carries [SqlSourceGenerate], or about the project. Ids from 101 to 127 are about the contents of a .sql file.

Area Ids Reported by Where
Project and attribute SQLSRC001, SQLSRC002, SQLSRC003, SQLSRC004, SQLSRC005, SQLSRC007, SQLSRC008, SQLSRC009, SQLSRC012, SQLSRC013 The build In the C# file, at the type's name or its [SqlSourceGenerate]. SQLSRC008, SQLSRC009 and SQLSRC013 are in the .sql file
Settings files SQLSRC015, SQLSRC016, SQLSRC017, SQLSRC018, SQLSRC019, SQLSRC020 The build and the tool, but SQLSRC020 the build alone At the line and column in the settings file
The compiler SQLSRC021 The build Before the build compiles anything
Projects that share SqlSource's exceptions SQLSRC022, SQLSRC023 The build No file and line, once for the project
A build that runs the tool SQLSRC024, SQLSRC025, SQLSRC026, SQLSRC027 The build At the project file
Repositories SQLSRC028, SQLSRC029, SQLSRC030, SQLSRC031, SQLSRC032, SQLSRC033, SQLSRC034, SQLSRC035, SQLSRC036, SQLSRC037 The build In the C# file, at the type's [SqlSourceGenerate] or at the member that the error names. SQLSRC032 and SQLSRC033 of a factory's member are at the field, property or parameter that holds the factory. Only for a type that claims a query whose output is repository, but SQLSRC032 of a static member of the project, or of a mark that can never give a connection, which is at the mark whatever the queries. A static member of a base type of a repository is the repository's own member, and is reported with it
Projects that share SqlSource's exceptions across frameworks SQLSRC038 The build No file and line, once for the project
.sql files SQLSRC101, SQLSRC102, SQLSRC103, SQLSRC104, SQLSRC105, SQLSRC106, SQLSRC107, SQLSRC108, SQLSRC109, SQLSRC110, SQLSRC111, SQLSRC112, SQLSRC113, SQLSRC114, SQLSRC115, SQLSRC116, SQLSRC117, SQLSRC118, SQLSRC119, SQLSRC120, SQLSRC121, SQLSRC122, SQLSRC123, SQLSRC124, SQLSRC125, SQLSRC126, SQLSRC127 The build and the tool, but SQLSRC121 to SQLSRC125 and SQLSRC127 the build alone At the line and column in the .sql file
The tool SQLSRC200, SQLSRC201, SQLSRC202, SQLSRC203, SQLSRC204, SQLSRC205, SQLSRC206, SQLSRC207, SQLSRC208, SQLSRC209, SQLSRC210, SQLSRC211, SQLSRC212, SQLSRC213, SQLSRC214, SQLSRC215, SQLSRC216, SQLSRC217, SQLSRC218, SQLSRC219, SQLSRC220, SQLSRC221, SQLSRC222, SQLSRC223 The tool, and SQLSRC209 and SQLSRC210 the build too At the query, the file, the project or the solution that the error is about. Some have no file
Describing a query SQLSRC224, SQLSRC225, SQLSRC226, SQLSRC227, SQLSRC228, SQLSRC229, SQLSRC230, SQLSRC231, SQLSRC232, SQLSRC233, SQLSRC234, SQLSRC235, SQLSRC236 The tool In the .sql file, at the query's name. An error about the database is at its first query
The sidecar of a .sql file SQLSRC237, SQLSRC238, SQLSRC239, SQLSRC240, SQLSRC241, SQLSRC242, SQLSRC243, SQLSRC244, SQLSRC245 The build In the sidecar of a .sql file that a type uses, at the line and column of the problem. SQLSRC241 to SQLSRC244 are at the query in the .sql file
The C# types of a query SQLSRC246, SQLSRC247, SQLSRC248, SQLSRC249 The build At the query's name. SQLSRC247 and SQLSRC248 have no file and line, and are reported once for the project
A C# type of your choice SQLSRC250, SQLSRC251, SQLSRC252 The build At the name of each query that has a column or a parameter of the type
The models of a query SQLSRC253, SQLSRC254, SQLSRC255, SQLSRC256, SQLSRC257, SQLSRC258, SQLSRC259, SQLSRC260 The build At the query's name, or at the marker that the error is about
An entry of the type override that maps nothing SQLSRC261 The build At the query's name
The parameters of a SQL Server query SQLSRC262 The tool At the query's name
The columns of a SQL Server query SQLSRC263, SQLSRC264, SQLSRC265, SQLSRC266 The tool At the query's name
The C# types of a SQL Server query SQLSRC267, SQLSRC268, SQLSRC269, SQLSRC270 The build At the query's name. SQLSRC267 and SQLSRC268 have no file and line, and are reported once for the project
The encoding of a file SQLSRC271 The tool At the .sql file, with no line and column. For a C# file, at its Source or at the type's name
The methods of a query SQLSRC272, SQLSRC273, SQLSRC274, SQLSRC275, SQLSRC276 The build At the query's name. SQLSRC273 has no file and line. SQLSRC276 is at the type's [SqlSourceGenerate]
Converters SQLSRC277, SQLSRC278, SQLSRC279, SQLSRC280 The build At the converter's name in the C# file, or at the query's name
The libraries of a query SQLSRC281, SQLSRC282 The build SQLSRC281 is at the entry of the settings file or the marker that turns the library on. SQLSRC282 has no file and line
The JSON opt-in SQLSRC283 The build At the query's name
A short name of your choice SQLSRC284 The build At the query's name
A .env file SQLSRC285, SQLSRC286, SQLSRC287 The tool At the .env file, or at the line and column of a variable in it. SQLSRC287 is at the folder that is watched
A bug-report bundle SQLSRC288, SQLSRC289, SQLSRC290, SQLSRC291 The tool At the bundle
Making a bug report with diagnose SQLSRC292, SQLSRC293, SQLSRC294, SQLSRC295, SQLSRC296 The tool At the bundle. SQLSRC292 is at the .sql file
The collection method of a query SQLSRC297 The build At the query's name
A query's synchronous method SQLSRC298, SQLSRC299 The build At the query's name

SQLSRC224 to SQLSRC236, and SQLSRC262 to SQLSRC266, are the errors of describing a query against its database, PostgreSQL or SQL Server. The section of each names the database that gives it.

The build checks the models of a query, SQLSRC253 to SQLSRC260, only while the query's entry in its sidecar is current. For SQLSRC253 to SQLSRC258, each column and parameter of the query must also have a C# type.