|
| 1 | +# Troubleshoot Azure Form Recognizer client library issues |
| 2 | + |
| 3 | +This troubleshooting guide contains information to help diagnose frequently encountered issues while using the Azure Form Recognizer client library for JavaScript. |
| 4 | + |
| 5 | +## Table of Contents |
| 6 | + |
| 7 | +- [Troubleshooting Errors](#troubleshooting-errors) |
| 8 | + - [Handling RestError](#handling-resterror) |
| 9 | + - [Build model error](#build-model-error) |
| 10 | + - [Invalid training dataset](#invalid-training-data-set) |
| 11 | + - [Invalid SAS URL](#invalid-sas-url) |
| 12 | + - [Generic Error](#generic-error) |
| 13 | +- [Unexpected time to build a custom model](#unexpected-time-to-build-a-custom-model) |
| 14 | +- [Form Recognizer errors](#form-recognizer-errors) |
| 15 | +- [Logging](#logging) |
| 16 | + |
| 17 | +## Troubleshooting Errors |
| 18 | + |
| 19 | +### Handling RestError |
| 20 | + |
| 21 | +Form Recognizer service methods throw [`RestError`] on failure. |
| 22 | + |
| 23 | +The RestError raised by the Azure Form Recognizer client library includes detailed error response information that provides useful insights into what went wrong and includes corrective actions to fix common issues. |
| 24 | +This error information can be found in the `RestError#message` property. |
| 25 | + |
| 26 | +### Build model error |
| 27 | + |
| 28 | +When building a model, the most common errors are caused by an [invalid data set](#invalid-training-data-set) or an [invalid SAS Url](#invalid-sas-url). |
| 29 | + |
| 30 | +#### Invalid training data set |
| 31 | + |
| 32 | +This error indicates that the provided data set does not match the training data requirements. |
| 33 | +Learn more about building a training data set [on Microsoft Learn by following this link](https://aka.ms/customModelV3). |
| 34 | + |
| 35 | +Example error below: |
| 36 | + |
| 37 | +``` |
| 38 | + RestError: Invalid request. |
| 39 | + { |
| 40 | + "name": "RestError", |
| 41 | + "code": "InvalidRequest", |
| 42 | + "statusCode": 400, |
| 43 | + . |
| 44 | + . |
| 45 | + . |
| 46 | + . |
| 47 | + "details": { |
| 48 | + "error": { |
| 49 | + "code": "InvalidRequest", |
| 50 | + "message": "Invalid request.", |
| 51 | + "innererror": { |
| 52 | + "code": "InvalidContent", |
| 53 | + "message": "The file is corrupted or format is unsupported. Refer to documentation for the list of supported formats." |
| 54 | + } |
| 55 | + } |
| 56 | + }, |
| 57 | + "message": "Invalid request." |
| 58 | + } |
| 59 | +``` |
| 60 | + |
| 61 | +#### Invalid SAS URL |
| 62 | + |
| 63 | +This error points to missing permissions on the blob storage SAS URL for the Form Recognizer service to access the training dataset resource. For more information about SAS tokens for Form Recognizer, see [here](https://learn.microsoft.com/azure/applied-ai-services/form-recognizer/create-sas-tokens). |
| 64 | + |
| 65 | +Example error: |
| 66 | + |
| 67 | +``` |
| 68 | + RestError: Invalid argument. |
| 69 | + { |
| 70 | + "name": "RestError", |
| 71 | + "code": "InvalidArgument", |
| 72 | + "statusCode": 400, |
| 73 | + . |
| 74 | + . |
| 75 | + . |
| 76 | + "details": { |
| 77 | + "error": { |
| 78 | + "code": "InvalidArgument", |
| 79 | + "message": "Invalid argument.", |
| 80 | + "innererror": { |
| 81 | + "code": "InvalidSasToken", |
| 82 | + "message": "The shared access signature (SAS) is invalid: SAS token expired on 10/04/2022 03:19:05 +00:00" |
| 83 | + } |
| 84 | + } |
| 85 | + }, |
| 86 | + "message": "Invalid argument." |
| 87 | + } |
| 88 | +``` |
| 89 | + |
| 90 | +### Generic Error |
| 91 | + |
| 92 | +Seeing a "Generic error" returned from the SDK is most often caused by heavy load on the service. For troubleshooting issues related to service limits, see related information [here](https://learn.microsoft.com/azure/applied-ai-services/form-recognizer/service-limits?tabs=v30). |
| 93 | + |
| 94 | +Example error: |
| 95 | + |
| 96 | +``` |
| 97 | +(3014) Generic error during training. |
| 98 | +Invalid model created with ID=<model ID> |
| 99 | +``` |
| 100 | + |
| 101 | +### Unexpected time to build a custom model |
| 102 | + |
| 103 | +Training(`DocumentModelAdministrationClient#beginBuildDocumentModel()`) with the "neural" build mode typically takes significantly longer than the "template" mode. |
| 104 | + |
| 105 | +For simpler use-cases, you can use the `template` build mode which uses a different model building algorithm that takes less time. Neural models are trained using deep learning, so they are more computationally intensive to train and use. More information about the `template` and neural build modes and the characteristics of models created using each can be found at the following Microsoft Learn pages: |
| 106 | + |
| 107 | + |
| 108 | +- [Custom template models](https://aka.ms/custom-template-models) |
| 109 | +- [Custom neural models](https://aka.ms/custom-neural-models) |
| 110 | + |
| 111 | +_See also_: [`DocumentModelBuildMode` reference documentation](https://docs.microsoft.com/javascript/api/@azure/ai-form-recognizer/documentmodelbuildmode). |
| 112 | +### Form Recognizer errors |
| 113 | + |
| 114 | +For information about the error messages and codes produced by the Form Recognizer service, please refer to [the service's error documentation][fr-errors]. |
| 115 | + |
| 116 | +### Logging |
| 117 | + |
| 118 | +Enabling logging may help uncover useful information about failures. In order to see a log of HTTP requests and responses, set the `AZURE_LOG_LEVEL` environment variable to `info`. Alternatively, logging can be enabled at runtime by calling `setLogLevel` in the `@azure/logger`: |
| 119 | + |
| 120 | +```javascript |
| 121 | +const { setLogLevel } = require("@azure/logger"); |
| 122 | + |
| 123 | +setLogLevel("info"); |
| 124 | +``` |
| 125 | + |
| 126 | + |
| 127 | +For more detailed instructions on how to enable logs, you can look at the [@azure/logger package docs](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/core/logger). |
| 128 | + |
| 129 | + |
| 130 | + |
| 131 | +[`resterror`]: https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/core/core-rest-pipeline/src/restError.ts |
| 132 | +[fr-errors]: https://aka.ms/azsdk/formrecognizer/errors |
0 commit comments