Reference

PersistedOperationException

Package Trax.Api.GraphQL.PersistedOperationsNamespaces Trax.Api.GraphQL.PersistedOperations.Storage.Exceptions, Trax.Api.GraphQL.PersistedOperations.StorageSource PersistedOperationException.cs, PersistedOperationParseException.cs, PersistedOperationValidationException.cs, PersistedOperationInputException.cs, PersistedOperationNotBroadcastException.cs, ValidationFailure.cs, ShapeDiffViolationException.cs

Abstract base for every structured failure raised by IPersistedOperationStore: a refused upload, or a saved change that did not reach every node. It derives from InvalidOperationException.

Signature

public abstract class PersistedOperationException : InvalidOperationException
{
    public abstract string Code { get; }
}

Members

Every subclass is sealed, returns its code from Code, and carries the same code as the public constant CodeValue, matching the code field of the management mutations' errors[] payload. ShapeDiffViolationException is in Trax.Api.GraphQL.PersistedOperations.Storage; the others are in Trax.Api.GraphQL.PersistedOperations.Storage.Exceptions.

SubclassCodeWhen
PersistedOperationParseExceptionPARSE_FAILEDDocument failed Utf8GraphQLParser.Parse.
PersistedOperationValidationExceptionSCHEMA_VALIDATION_FAILEDDocument parsed but failed HotChocolate validation.
ShapeDiffViolationExceptionSHAPE_DIFF_VIOLATIONEdit changes the response shape of an existing id.
PersistedOperationInputExceptionINVALID_INPUTDocument holds no operation, or more than one. A persisted document holds exactly one.
PersistedOperationNotBroadcastExceptionCHANGE_NOT_BROADCASTAn upload, deactivation or restore was saved and applied on this node, but the broker did not confirm its broadcast.

PersistedOperationParseException

PropertyTypeNotes
CodestringAlways "PARSE_FAILED".
Lineint?1-based line number when the parser exposed one.
Columnint?1-based column number when the parser exposed one.
OriginalMessagestringThe parser's original message, preserved without prefixing.

PersistedOperationValidationException

PropertyTypeNotes
CodestringAlways "SCHEMA_VALIDATION_FAILED".
FailuresIReadOnlyList<ValidationFailure>One entry per HotChocolate validation error. Construction throws ArgumentException for an empty list (a validation exception with no failures is meaningless).

ValidationFailure is a record with:

FieldTypeNotes
MessagestringValidator-provided message.
LocationsIReadOnlyList<ValidationFailureLocation>Empty when not available.
PathIReadOnlyList<object>Response-path components leading to the failure. Empty when not applicable.

ValidationFailure.FromMessage(message) builds a failure with no locations and no path. ValidationFailureLocation is a record struct of Line and Column, 1-based.

ShapeDiffViolationException

PropertyTypeNotes
CodestringAlways "SHAPE_DIFF_VIOLATION".
IdstringThe id whose shape would change.
OldFingerprintstringFingerprint stored on the existing row.
NewFingerprintstringFingerprint computed from the proposed new document.

UpsertOptions { BypassShapeDiff = true } (or bypassShapeDiff: true on the GraphQL mutation) skips the check. The exception's message names the C# option; the mutation's SHAPE_DIFF_VIOLATION error names bypassShapeDiff: true.

PersistedOperationInputException

PropertyTypeNotes
CodestringAlways "INVALID_INPUT".

Thrown after validation, for every validator including the no-op one AddPersistedOperationStore registers.

PersistedOperationNotBroadcastException

PropertyTypeNotes
CodestringAlways "CHANGE_NOT_BROADCAST".
IdstringThe id of the operation that changed.
OperationPersistedOperation?The row as saved, for an upload; null for a deactivation or a restore.
InnerExceptionExceptionThe broadcaster's failure: a refused or unanswered publisher confirm (ten seconds), or no connection to the broker.

Unlike the other subclasses, the change it reports is committed. The node that made it has already emptied its caches; every other node keeps serving what it cached until that entry reaches its maximum age (WithCacheMaxAge), then reads the store again. Repeating the change (re-upload the same document, deactivate again) sends it again. The management mutations return it as a payload error beside the saved operation.

Behavior

Request errors

Two refusals happen when a request is executed, not when an operation is stored, so they are GraphQL errors in the response's top-level errors rather than exceptions. Both answer HTTP 400.

extensions.codeWhen
PERSISTED_OPERATION_REQUIREDEnforcement refuses an inline document. See UsePersistedOperationsEnforcement.
PERSISTED_OPERATION_ID_MISMATCHThe request sends a persisted operation id and a document, and the id is not the document's own hash under the executor's hash algorithm. Send the id alone to run the stored operation, or the document alone to run it inline. See Persisted Operations.

Every code the endpoint returns is listed in Error Codes.

Example

var store = serviceProvider.GetRequiredService<IPersistedOperationStore>();
 
try
{
    await store.UpsertAsync("userProfile_v1", candidateDocument, options: null, ct);
}
catch (ShapeDiffViolationException ex)
{
    Console.Error.WriteLine($"{ex.Code}: {ex.OldFingerprint} -> {ex.NewFingerprint}");
}
catch (PersistedOperationNotBroadcastException ex)
{
    Console.Error.WriteLine($"{ex.Id} saved, other nodes not told: {ex.InnerException?.Message}");
}
catch (PersistedOperationException ex)
{
    Console.Error.WriteLine($"{ex.Code}: {ex.Message}");
}

See also