Skip to content

fix(parser)!: throw ParsingException for a value that does not convert - #162

Merged
pdevito3 merged 3 commits into
v2from
fm/qk-breaking-2x
Oct 3, 2026
Merged

pdevito3 merged 3 commits into
v2from
fm/qk-breaking-2x

Conversation

@pdevito3

@pdevito3 pdevito3 commented Oct 1, 2026 •

Copy link
Copy Markdown
Owner

Summary

A filter value that does not convert to the type of its property now always throws ParsingException. Before this change, some bad values escaped the QueryKitException hierarchy. A consumer that catches only QueryKitException returned a 500 for them.

  • ParseFilter catches FormatException and OverflowException and throws ParsingException.

  • An enum list value such as BirthMonth ^^ ["Bogus"] or BirthMonth ^^ [Bogus] leaked a raw ArgumentException from Enum.Parse. It now throws ParsingException.

  • Every conversion site (scalar, list, enum, Guid, DateTime, DateTimeOffset, DateOnly, TimeOnly) uses one path.

  • The message names the value, the target type, and the property name as the client wrote it (the query name, not the member path):

    The value 'Bogus' is not a valid BirthMonthEnum for the filter property 'BirthMonth'.

  • The culture number fallback (for example Rating > 4.4 in de-DE) keeps this message. Before, it replaced the message with the generic parsing message.

  • The original exception stays on InnerException.

Migration

  • If you catch FormatException, OverflowException, or ArgumentException from ApplyQueryKitFilter, catch ParsingException (or QueryKitException) instead.
  • If you match on the old message for an invalid enum value ("There was a parsing failure..."), match on the new message.

Evidence

The verify-querykit harness ran on the memory and Postgres targets. The model has Visibility (enum) and Rating (int).

Filter Before After
Visibility ^^ ["Bogus"] System.ArgumentException "Requested value 'Bogus' was not found." (exit 1) ParsingException "The value 'Bogus' is not a valid Visibility for the filter property 'Visibility'." (exit 2)
Visibility ^^ [Bogus] System.ArgumentException (exit 1) ParsingException, same message (exit 2)
Visibility ^^ [Public, Bogus] System.ArgumentException (exit 1) ParsingException, same message (exit 2)
Visibility == "Bogus" ParsingException with the generic message ParsingException that names the value
Rating == "abc" ParsingException with the generic message "The value 'abc' is not a valid Int32 for the filter property 'Rating'."
Visibility ^^ ["Private"] 2 rows 2 rows (no change)

Tests:

  • New unit tests cover the message for enum, Int32, Decimal, Guid, DateTime, Boolean, and list values. One test covers a query name alias (month). One test covers the comma culture fallback.
  • New integration cases cover the enum list form on Postgres.
  • Unit: 600 passed. Integration: 365 passed. dotnet build -warnaserror: 0 warnings.
  • The verify-querykit feature map no longer lists Rating > "abc" and Title @= null as escapes from QueryKitException.

Merge Danger

  • Breaking: the exception type changes for some bad values, and the message text changes for all bad values. See Migration.
  • The message contains the client value. A server that returns the message to the client echoes the client input. It does not contain internal type paths beyond the short type name.

A value that does not convert to the property type (for example `Age == "abc"`, `Rating > abc`, or an int overflow) threw FormatException or OverflowException. It now throws ParsingException, with the original exception as the inner exception.

BREAKING CHANGE: a bad filter value throws ParsingException, not FormatException or OverflowException. Catch ParsingException or QueryKitException instead. The inner exception keeps the original details.
…hat does not convert

An enum list value such as BirthMonth ^^ ["Bogus"] leaked a raw ArgumentException from Enum.Parse. Every conversion site now throws ParsingException. The message names the value, the target type, and the query name that the client wrote. The culture number fallback keeps this message instead of the generic one.
@pdevito3
pdevito3 merged commit b2d085b into v2 Oct 3, 2026
2 checks passed
@pdevito3
pdevito3 deleted the fm/qk-breaking-2x branch October 3, 2026 12:15
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant