Skip to content

Error handling: Fine-grained top-level error codes - #1697

Open
mgovers wants to merge 6 commits into
pgm/feature/error-codes-in-corefrom
pgm/feature/fine-grained-base-error-types
Open

mgovers wants to merge 6 commits into
pgm/feature/error-codes-in-corefrom
pgm/feature/fine-grained-base-error-types

Conversation

@mgovers

@mgovers mgovers commented Nov 13, 2026 •

Copy link
Copy Markdown
Member

Part of #509

Cherry-picked from #1635

⚠️ DISCLAIMER: this may affect C API users if they use an exact match pattern to check for error types (intentionally undefined behavior).

What is new

This PR replaces many instances in which the generic catch-all PGM_regular_error error code was reported, with the following new, more fine-grained error codes that represent error categories.

    PGM_dataset_error = 4,       /**< Error occurs during dataset handling. */
    PGM_data_error = 5,          /**< There was a problem with the contents of the provided data. */
    PGM_calculation_error = 6,   /**< Error occurs during the actual calculation. */
    PGM_illegal_operation =
        7,                   /**< An illegal operation was attempted to the C API, such as accessing a null pointer. */
    PGM_bad_request = 8,     /**< A bad request was attempted to the C API, such as providing the wrong dataset type. */
    PGM_not_implemented = 9, /**< The functionality is either not supported or not yet implemented. */
    PGM_internal_error = 10, /**< There was an internal error. */
    PGM_unknown_error = 255, /**< An unknown error occurred. */

In #1635, additional subtypes will be added that are (modulo 256) the same as this type, i.e. (derived - base) % 256 == 0 if derived is a subtype of base and 0 < base < 256 and 0 < derived.

This change therefore enables more fine-grained control of error handling mechanisms. Of course, it is important to note that it is not good to depend too much on that for stability reasons, but it is nice to have options, rather than to depend on only error messages.

Rationale

Why we are doing this change

Errors are sometimes difficult to decode. PGM_regular_error is not very descriptive and up til now, one had to rely on string decoding or regex pattern matching. While that works to some extend, this is not really sustainable and even less stable (e.g. correcting a typo may break the pattern matching). In PGM, the Python API, in particular, suffers from this issue. #509 has been open in this regard for a long time.

Why we do not consider this change breaking

We consider the precise error being reported to be intentionally undefined behavior, particularly of the unspecified behavior class. A user is only affected if their program strongly depends on the precise error type and therefore depends on undefined behavior.

What we took into consideration

  • None of the C API calls define the error being reported to be of a specific type. It is therefore unspecified which exact error type is reported for each API call.
    • Following the open/closed SOLID principle, error codes are intended to be extensible - that is, existing error codes will remain alive and carry the same meaning, at least within the same major version, but other error codes may be added for new issue types.
  • The name PGM_regular_error already suggests that there may be other error types and that types may change in the future.
  • An already existing example that has been in the code for a long time is that batch calculations may result in either PGM_regular_error or PGM_batch_error, depending on the type of issue encountered.

Which users are affected?

Users may be affected if they use a pattern like the example below.

Users that only depend on PGM_no_error are not affected. PGM_no_error is, and will remain, an invariant of PGM.

switch (PGM_error_code(handle)) {
  case PGM_regular_error:
    return handle_regular_errors(handle);
  case PGM_batch_error:
    return handle_batch_errors(handle);
  // exhaustive list
  default:
    return handle_other_errors(handle); // this will now happen more often as many PGM_regular_errors were replaced by another error type
}

Weakly affected users (users with good fall-back mechanisms)

If handle_other_errors is simply a fall-back to report nicely the encountered error, then the user can benefit from the alternatives below, but the change for sure is not breaking to them.

Strongly affected users (users that invoke undefined behavior)

If handle_other_errors is a strong fallback mechanism, e.g. calls abort() when an unknown error is encountered, then the user strongly depends on undefined behavior and this change will affect them. Since it concerns undefined behavior, this is the user's responsibility to resolve this.

Alternatives

Instead of hard matching, users can use 2 options that we foresee stable going forward.

Option 1: use PGM_error_code_is_subcode_of(error_code, base_error_code)

This is guaranteed to be stable and future-proof, even as we add more error types and levels. However, exhaustive listing is mostly recommended in case the total amount of

auto const error_code = PGM_error_code(handle);
if (PGM_error_code_is_subcode_of(error_code, PGM_regular_error) {
    return handle_regular_errors(handle);
}
if (PGM_error_code_is_subcode_of(error_code, PGM_batch_error) {
    return handle_batch_errors(handle);
}
// ... finer-grained subcodes are needed here
if (PGM_error_code_is_subcode_of(error_code, PGM_unknown_error) {
    return handle_other_errors(handle);
}

Option 2: use a custom modulo/bit-masking approach

We intend to keep error codes stable modulo 256, i.e., we are adopting a multi-level error code schema, in which every level has 8 bits. In the foreseeable future, we are restricting to 4 levels, giving 32-bits of error code information, which is sufficient for most cases.

switch (PGM_error_code(handle) % 256) { // or & 0xFF
  case PGM_regular_error:
    return handle_regular_errors(handle);
  case PGM_batch_error:
    return handle_batch_errors(handle);
  default:
    return handle_other_errors(handle);
}

PR stack structure

PR purpose
#1695 minor chores found along the way
#1696 core implementation
#1697 use fine-grained top-level error codes ⚠️ no longer only only raise PGM_regular_error
#1635 C API additions + usage

@mgovers mgovers self-assigned this Nov 13, 2026
@mgovers mgovers added the feature New feature or request label Nov 13, 2026
@mgovers
mgovers force-pushed the pgm/feature/fine-grained-base-error-types branch from efe2751 to 0ca6ad4 Compare November 13, 2026 12:16
Signed-off-by: Martijn Govers <Martijn.Govers@Alliander.com>
Signed-off-by: Martijn Govers <Martijn.Govers@Alliander.com>
@mgovers
mgovers force-pushed the pgm/feature/fine-grained-base-error-types branch from e57de7d to af331d7 Compare November 13, 2026 13:05
Signed-off-by: Martijn Govers <Martijn.Govers@Alliander.com>
Signed-off-by: Martijn Govers <Martijn.Govers@Alliander.com>
@mgovers mgovers added the do-not-merge This should not be merged temporarily label Nov 16, 2026
@mgovers

mgovers commented Nov 16, 2026

Copy link
Copy Markdown
Member Author

do-not-merge label added pending some internal discussion

Signed-off-by: Martijn Govers <Martijn.Govers@Alliander.com>
Signed-off-by: Martijn Govers <Martijn.Govers@Alliander.com>
@sonarqubecloud

Copy link
Copy Markdown

Quality Gate Failed Quality Gate failed

Failed conditions
52.4% Coverage on New Code (required ≥ 80%)

See analysis details on SonarQube Cloud

@mgovers

mgovers commented Nov 17, 2026

Copy link
Copy Markdown
Member Author

@WinApiMan, Will this change affect you, and if so, in what way?

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

do-not-merge This should not be merged temporarily feature New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant