Skip to content

Troubleshoot Common Issues

Daniel Dieckmann edited this page Nov 6, 2026 · 2 revisions

Troubleshoot Common Issues

Last verified against v3.0.0 (live-D365 items dated per run)

Each entry is keyed by the error you see. Match the symptom, read the one-line cause, apply the fix. Live-server behaviour is dated to the smoke run that proved it.

HTTP 403 ODataSecurityException — "update not allowed for field 'X'"

D365 rejected an UpdateCommand<T> because the PATCH payload carried a field that is read-only on update. The offending field needs [ODataField(IgnoreOnUpdate = true)] so the payload builder omits it.

Warning

One read-only field in the payload makes D365 reject the whole PATCH with HTTP 403 — not only that field. The other fields never land. Mark every read-only field IgnoreOnUpdate, or the update fails entirely.

On LedgerJournalHeader these fields are read-only on update and already carry the attribute: JournalName, IsPosted, JournalTotalDebit, JournalTotalCredit, AccountingCurrency. If you extend the entity or add a new one, audit every property against D365's update semantics.

Result<LedgerJournalHeader> result = await mediator.Send(
    new UpdateCommand<LedgerJournalHeader>(header), cancellationToken);

if (result.IsFailed)
{
    IntegrationError? error = result.GetError();
    // On a stray read-only field the OData layer surfaces the 403 as a failed Result.
    // error?.Type == ErrorType.Failure; error?.Code == "LedgerJournalHeader.Unauthorized".
    // error?.Exception is the wrapped ODataClientException — its ResponseBody carries D365's
    // ODataSecurityException and the "update not allowed for field 'X'" detail. The host log
    // records the same body, truncated to 1,024 characters.
}

To send a field D365 rejects, do not remove the attribute globally — subclass the entity and re-declare the property with the corrected flag (see Errors when registering a custom entity below).

Verified against live D365 (JFI) on 2026-07-01: the five LedgerJournalHeader fields above were surfaced by an all-green LedgerJournal CRUD run once they were marked IgnoreOnUpdate.

HTTP 401 with ReasonPhrase "Authentication failed"

ODataAuthenticationHandler could not acquire a bearer token, so it short-circuited the request before it reached D365. The 401 carries the fixed generic phrase and no MSAL detail. The handler discards the MSAL error and nothing logs it, so the mediator result says only that authentication failed:

if (result.IsFailed)
{
    IntegrationError? error = result.GetError();
    // error?.Code == "LedgerJournalHeader.Unauthorized"  ({Entity}.Unauthorized)
    // error?.Type == ErrorType.Failure; error?.Message == "Authentication or authorisation failure".
}

{Entity}.Unauthorized covers this short-circuit and a 401 or 403 returned by D365 itself. To see the MSAL error, call the injected IAuthenticator directly with the same credentials — only this path returns Auth.Msal.{code}:

ODataOAuthSettings oauth = odataOptions.Value.Authentication.OAuth;   // IOptions<ODataSettings>

Result<string> token = await authenticator.GetAccessTokenAsync(
    oauth.ClientId, oauth.ClientSecret, oauth.TenantId, oauth.Resource, cancellationToken);

if (token.IsFailed)
{
    IntegrationError? error = token.GetError();
    // error?.Code == "Auth.Msal.invalid_client"  (Auth.Msal.{MSAL error code})
    // error?.Exception is the MsalException; its message carries the AADSTS code — log it server-side only.
}

Read the AADSTS code from the exception message and act on it:

AADSTS code Cause Fix
AADSTS7000215 Invalid client secret Rotate the secret in Azure AD, re-deploy via Key Vault
AADSTS50012 Secret truncated or malformed Re-copy the secret from Azure AD verbatim
AADSTS700016 App not found in the tenant Set TenantId to the tenant where the app is registered
AADSTS70011 Wrong resource Set the resource to the environment URL without /data

If the token is acquired but D365 still returns 401, register the app as a service user in D365 F&O (System administration -> Setup -> Azure Active Directory applications). See Authentication Modes.

"Could not find a property named 'X'"

D365 rejected the filter, select, or payload because a camelCase wire field was declared without [JsonPropertyName]. About 479 legacy X++ fields (dataAreaId, transDate, validFrom, recId) are camelCase on the wire; the CLR property is PascalCase by C# convention, so the two must be bridged.

Add [JsonPropertyName("camelCaseName")] to the property. IntegratoR's filter/select/expand/$orderby translator honours the attribute, so a typed LINQ filter then emits the right wire name.

[Key]
[JsonPropertyName("dataAreaId")]              // wire name is camelCase
[ODataField(IsRequired = true)]
public required string DataAreaId { get; set; }

With the attribute in place, x => x.DataAreaId == "USMF" emits $filter=dataAreaId eq 'USMF'. Without it, the translator reads the PascalCase CLR name and D365 fails the request. Never write raw OData filter strings — use typed LINQ throughout.

A value you set on create is silently dropped

The property carries [ODataField(IgnoreOnCreate = true)], so the payload builder omits it from the POST. The create succeeds, but your value never reached D365. On LedgerJournalHeader, JournalBatchNumber is IgnoreOnCreate because a D365 number sequence assigns it — read it back from result.Value.JournalBatchNumber after the create.

Result<LedgerJournalHeader> result = await mediator.Send(
    new CreateCommand<LedgerJournalHeader>(header), cancellationToken);

if (result.IsSuccess)
{
    // The server-assigned batch number is on the returned entity, not the one you sent.
    string batchNumber = result.Value.JournalBatchNumber!;
}
else
{
    IntegrationError? error = result.GetError();
    // A rejected create fails the Result — inspect error?.Code and error?.Message for the D365 detail.
}

If you must send a field D365 accepts on create but the framework entity ignores, subclass and re-declare the property with IgnoreOnCreate = false (see below). If D365 accepts the field for every consumer, fix the attribute on the framework entity instead — see Known Limitations.

Validation.Error returned before any request reaches D365

ValidationBehaviour ran a registered IValidator<TRequest>, a rule failed, and the pipeline short-circuited. The handler never ran, so nothing reached D365. This is the framework working as intended, not a fault.

if (result.IsFailed)
{
    IntegrationError? error = result.GetError();
    // error?.Code == "Validation.Error"; error?.Type == ErrorType.Validation.
    // error?.Message is the FIRST failing rule's message — later failures are dropped.
}

Read error.Message for the first failing rule and correct the input. To surface every failure at once, compose them in one RuleFor(...).Custom(...) rule that builds a multi-line message. See Add Validation.

Your validator never fires

The assembly holding the validator was not passed to AddConsumerHandlers. AddIntegratoR scans only the assemblies you register explicitly plus the framework assemblies — it does not scan every loaded assembly.

Register the assembly in the configure delegate:

services.AddIntegratoR(configuration, integrator =>
    integrator.AddConsumerHandlers(typeof(MyValidator).Assembly));

Generic command validators are closed over your entity types by the same scan (since v2.0.1), so registering the assembly also activates CreateCommand<T>/UpdateCommand<T> validation for your entities.

Errors when registering a custom entity

mediator.Send(...) was called with a command or query closed over a custom or extended entity whose assembly was never handed to AddConsumerHandlers. MediatR then has no closed handler to resolve.

InvalidOperationException: No service for type
'MediatR.IRequestHandler`2[...]' has been registered.

AddIntegratoR closes its generic handlers over an entity type only when that type's assembly is part of the combined handler scan. Register the assembly that holds your entity — nothing more:

services.AddIntegratoR(configuration, integrator =>
    integrator.AddConsumerHandlers(typeof(MyLedgerJournalLine).Assembly));

AddConsumerHandlers folds the assembly into the scan, so CreateCommand<MyLedgerJournalLine> — and Update/Delete/GetByKeyQuery/GetByFilterQuery — resolves. The service layer was never the gap: IService<T> is an open-generic registration that resolves against any type.

To override an inherited [ODataField] flag, re-declare the property on the subclass — overriding alone is not enough, because ODataFieldAttribute is inherited:

[Table("LedgerJournalLines")]
public class MyLedgerJournalLine : LedgerJournalLine
{
    [ODataField(IgnoreOnCreate = false)]      // re-declared flag wins
    [JsonPropertyName("AccountType")]
    public override LedgerJournalACType AccountType { get; set; }
}

The payload builder reflects on the runtime type, so an instance of the subclass picks up the re-declared attribute. The property must be virtual on the base entity.

{Entity}.BatchFailed from a batch command

At least one operation in a CreateBatchCommand<T>, UpdateBatchCommand<T>, or DeleteBatchCommand<T> failed. The message carries only the count; the per-item detail is on the BatchOutcome inside the error. See Send Commands for the failure modes.

Result<BatchOutcome> result = await mediator.Send(
    new CreateBatchCommand<LedgerJournalLine>(lines), cancellationToken);

if (result.IsFailed && result.GetError() is BatchIntegrationError batchError)
{
    // batchError.Code == "LedgerJournalLine.BatchFailed"; batchError.Message reports "{failed} of {total} AddBatch operations failed".
    foreach (BatchItemResult failure in batchError.Outcome.Failures)
    {
        // failure.Index (position in your list), failure.StatusCode, failure.Key, failure.ErrorMessage (D365 inner error)
    }
}

Read the outcome with these rules:

  • Atomic chunk rolled back. Every operation in that chunk is reported failed with the status of the operation D365 rejected — the valid ones included, because nothing in the chunk committed. Fix the bad record and re-send the whole chunk.
  • Chunks missing from the outcome. In Atomic mode with StopOnFirstFailedChunk (default true), chunks after the failed one are never sent and do not appear in Outcome.Items. The message then ends "(remaining chunks skipped after a failed chunk in Atomic mode)", so compare Outcome.Total with your input count to find what was never sent.
  • StatusCode 0. The chunk could not be sent or its response was lost — for example an open circuit breaker, a connection failure, or an HttpClient timeout — and ErrorMessage holds the exception message. The real outcome is unknown: an atomic changeset may have committed before the response was lost, and in ContinueOnError mode items sent earlier in that chunk may already have committed. Query by a business key before re-sending.
  • Every item 401. Authentication failed, so nothing ran — see the 401 entry above.

When the diagnostic is not here

For any error not listed above:

  1. Read the host log — the framework logs the normalised base URL at startup, every failed OData operation with its HTTP status and D365 response body (truncated), and every attempt of its two retry policies (see Configure Resilience).
  2. Run the financial-dimension smoke test (read-only, low-risk); it surfaces auth, network, and OData configuration errors as typed IntegrationError codes without writing to D365. See Run Smoke Tests.
  3. Match on the IntegrationError.Code — OData failures follow {Entity}.{Cause} (LedgerJournalHeader.Unauthorized, LedgerJournalHeader.NotFound, LedgerJournalLine.BatchFailed); validation failures use Validation.Error.
  4. Open an issue at the IntegratoR repository with the request URL, the IntegrationError shape, and the failing host-log lines.

See Also

Clone this wiki locally