Repository navigation
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.
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.
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.
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.
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.
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.
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.
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.
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
Atomicmode withStopOnFirstFailedChunk(defaulttrue), chunks after the failed one are never sent and do not appear inOutcome.Items. The message then ends "(remaining chunks skipped after a failed chunk in Atomic mode)", so compareOutcome.Totalwith your input count to find what was never sent. -
StatusCode0. The chunk could not be sent or its response was lost — for example an open circuit breaker, a connection failure, or anHttpClienttimeout — andErrorMessageholds the exception message. The real outcome is unknown: an atomic changeset may have committed before the response was lost, and inContinueOnErrormode 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.
For any error not listed above:
- 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).
- Run the financial-dimension smoke test (read-only, low-risk); it surfaces auth, network, and OData configuration errors as typed
IntegrationErrorcodes without writing to D365. See Run Smoke Tests. - Match on the
IntegrationError.Code— OData failures follow{Entity}.{Cause}(LedgerJournalHeader.Unauthorized,LedgerJournalHeader.NotFound,LedgerJournalLine.BatchFailed); validation failures useValidation.Error. - Open an issue at the IntegratoR repository with the request URL, the
IntegrationErrorshape, and the failing host-log lines.
-
Handle Errors — the
IntegrationErrorshape that carries these diagnostics - Run Smoke Tests — the fastest live diagnostic
- Authentication Modes — the auth-failure deep dive
- Known Limitations — behaviour that looks like a bug but has known status
Get Started
Use Cases
- Handle Errors
- Configure Resilience
- Add Validation
- Cache Query Results
- Work with Dimensions
- Run Smoke Tests
- Extend the Pipeline
- Test with TestKit
Reference