sdk/formrecognizer/Azure.AI.FormRecognizer/TROUBLESHOOTING.md
This troubleshooting guide contains instructions to diagnose frequently encountered issues while using the Azure Form Recognizer client library for .NET.
The RequestFailedException class, defined in the Azure.Core library, is the Exception type thrown by the Azure.AI.FormRecognizer clients on a service request failure. Its Message property provides detailed information about what went wrong and includes corrective actions to fix common issues.
For example, if you submit a receipt image with an invalid Uri, a 400 error is returned, indicating "Bad Request":
try
{
AnalyzeDocumentOperation operation = await client.AnalyzeDocumentFromUriAsync(WaitUntil.Completed, "prebuilt-receipt", new Uri("http://invalid.uri"));
}
catch (RequestFailedException e)
{
Console.WriteLine(e.ToString());
}
You will notice that additional information is logged, like the client request ID of the operation:
Message:
Azure.RequestFailedException: Service request failed.
Status: 400 (Bad Request)
ErrorCode: InvalidRequest
Content:
{"error":{"code":"InvalidRequest","message":"Invalid request.","innererror":{"code":"InvalidContent","message":"The file is corrupted or format is unsupported. Refer to documentation for the list of supported formats."}}}
Headers:
Transfer-Encoding: chunked
x-envoy-upstream-service-time: REDACTED
apim-request-id: REDACTED
Strict-Transport-Security: REDACTED
X-Content-Type-Options: REDACTED
Date: Fri, 01 Oct 2021 02:55:44 GMT
Content-Type: application/json; charset=utf-8
Error codes and messages raised by the Form Recognizer service can be found in the service documentation.
Build model errors may occur when trying to build a custom model. Usually they are caused by attempting to build the model with an invalid data set or an invalid SAS URL.
This error indicates that the provided data set does not match the training data requirements. Learn more about building a training data set here.
Example error output:
Azure.RequestFailedException : Invalid request.
Status: 400 (Bad Request)
ErrorCode: InvalidRequest
Content:
{
"error": {
"code": "InvalidRequest",
"message": "Invalid request.",
"innererror": {
"code": "TrainingContentMissing",
"message": "Training data is missing: Could not find any training data at the given path."
}
}
}
Headers:
Transfer-Encoding: chunked
x-envoy-upstream-service-time: 950
apim-request-id: 07838543-04d2-4427-be99-4d52bb834450
Strict-Transport-Security: max-age=31536000; includeSubDomains; preload
x-content-type-options: nosniff
Content-Type: application/json
Date: Tue, 04 Oct 2022 09:04:12 GMT
This error points to missing permissions on the blob storage SAS URL for the Form Recognizer service to access the training data set resource. For more information about SAS tokens for Form Recognizer, see here.
Example error output:
Azure.RequestFailedException : Invalid argument.
Status: 400 (Bad Request)
ErrorCode: InvalidArgument
Content:
{
"error": {
"code": "InvalidArgument",
"message": "Invalid argument.",
"innererror": {
"code": "InvalidSasToken",
"message": "The shared access signature (SAS) is invalid: SAS 'list' authorization is missing. Permissions: r"
}
}
}
Headers:
Transfer-Encoding: chunked
x-envoy-upstream-service-time: 20
apim-request-id: c3ab3235-3857-4485-85a7-5f6b11b6610b
Strict-Transport-Security: max-age=31536000; includeSubDomains; preload
x-content-type-options: nosniff
Content-Type: application/json
Date: Tue, 04 Oct 2022 09:19:33 GMT
Seeing a "Generic error" returned from the SDK is most often caused by a heavy load on the service. For troubleshooting issues related to service limits, see related information here.
Example error output:
Azure.RequestFailedException : Invalid model created with ID 046c569a-8a2a-43d0-b934-8bad2d6e7127
Status: 200 (OK)
ErrorCode: 3014
Additional Information:
error-0: 3014: Generic error during training.
Content:
Headers:
ms-azure-ai-errorcode: REDACTED
x-envoy-upstream-service-time: 30
apim-request-id: eda4204c-3432-4ea2-a056-990b795bd631
Strict-Transport-Security: max-age=31536000; includeSubDomains; preload
X-Content-Type-Options: nosniff
Date: Fri, 23 Sep 2022 04:20:08 GMT
Content-Length: 282
Content-Type: application/json; charset=utf-8
This error may occur when you use a FormRecognizerClient instance with a custom model built in Form Recognizer Studio. Form Recognizer Studio targets the latest version of the service, while the FormRecognizerClient class only supports older service versions.
See Analyze a document with a custom model
for a sample on how to use the new DocumentAnalysisClient. This new client supports newer service versions and can be used with models created in Form Recognizer Studio.
Example error output:
System.ArgumentException : The modelId must be a valid GUID.
Parameter name: modelId
----> System.FormatException : Guid should contain 32 digits with 4 dashes (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx).
It is common to have a long completion time when building a custom model using the Neural build mode with DocumentBuildMode.Neural.
For simpler use-cases, you can use DocumentBuildMode.Template which uses a different model building algorithm that takes less time. See more about Template custom models here. To see more information about Neural custom models, see the documentation here.
Reviewing the HTTP request sent or response received over the wire to/from the Azure Form Recognizer service can be useful when troubleshooting issues.
The simplest way to enable logs is by using the console logger.
To create an Azure SDK log listener that outputs messages to console use the AzureEventSourceListener.CreateConsoleLogger method:
// Setup a listener to monitor logged events.
using AzureEventSourceListener listener = AzureEventSourceListener.CreateConsoleLogger();
To learn more about other logging mechanisms see Diagnostics Samples.
NOTE: When logging the body of the request and the response, please ensure that they do not contain confidential information.