Troubleshooting
This page lists the API error responses Amazon Textract Insights returns and the common configuration pitfalls that cause them, with how to fix each.
API error responses
All APIs return standard AWS error responses. Which errors each operation can return is listed with that operation in the Amazon Textract Insights API Reference.
Error |
Cause |
Retry? |
|---|---|---|
|
Invalid input, such as a schema that fails validation, a reused
|
No. Fix the request. |
|
A parameter is malformed, such as a badly formed ARN, or a
|
No. Fix the request. |
|
The project or blueprint does not exist. |
No. |
|
|
No. |
|
Insufficient permissions, or the resource belongs to another account. |
No. |
|
A project or blueprint with that name already exists, or a concurrent update to the same resource conflicted. |
For a concurrent update, yes. Re-read the resource, then retry. |
|
An account quota was reached, such as projects or blueprints per account, versions per blueprint, or concurrent jobs. |
For concurrent jobs, retry after running jobs finish. The more pages you submit at once, the longer all jobs take. If you need more throughput, request a quota increase. |
|
Tagging APIs only. The tag quota for the resource was reached. |
No. |
|
Tagging APIs only. The request rate was too high. |
Yes, with exponential backoff. |
|
The request rate exceeded your throughput quota. |
Yes, with exponential backoff. |
|
Service error. |
Yes, with exponential backoff. |
When a job completes with Status FAILED, read
ErrorType and ErrorMessage from GetDocumentInsights
for the cause.
Common pitfalls
The following configuration mistakes are common causes of the errors in the preceding table.
Missing ExtractionConfiguration fields
ExtractionConfiguration is required on CreateProject, and
it must include BoundingBox, a non-empty
Granularity.Types list, and OutputFormat. Omitting any of them, or passing an empty
Granularity.Types, fails with ValidationException. To keep
extraction minimal when you only need custom extraction, pass:
{"BoundingBox": {"State": "DISABLED"}, "Granularity": {"Types": ["PAGE"]}, "OutputFormat": {"TextFormat": {"Types": ["MARKDOWN"]}, "AdditionalFileFormat": {"State": "DISABLED"}}}
Also note that on UpdateProject, a configuration block you include is
replaced in full, so an included ExtractionConfiguration must still
contain BoundingBox, Granularity, and
OutputFormat.
Inline object schema rejection
In a blueprint schema, define tables and nested structures with $defs
and $ref. An inline type: object is rejected with
ValidationException ("Blueprint has invalid schema"). See Blueprint schemas.
Job fails with PageLimitExceeded or DocumentTooLargeException
Page limits are checked after the job starts, so StartDocumentInsights
succeeds and the job ends FAILED. Check ErrorType:
-
PageLimitExceeded. The file has more pages than the service accepts. Split the file before you submit it. -
DocumentTooLargeException("The input document size is too large to process."). Despite the wording, this error can come from a page-count limit rather than file size. For example, either custom extraction ran without splitting on a file over the no-splitting page limit, or figure captioning was enabled on a file over the figure-captioning page limit. Both return the same message. If the job used custom extraction without splitting, enableSplitterConfigurationfirst, because that limit is lower. If the error persists, turn off figure captioning or submit a shorter file.
For the page limits, see Limits and quotas.
Bucket AWS Region mismatch
The input and output Amazon S3 buckets must be in the same AWS Region as the request. A
bucket in another AWS Region causes the job to fail. Confirm the buckets and the
--region you call with all match.
Reading OutputConfiguration as a folder instead of job_metadata.json
On SUCCEEDED, OutputConfiguration.S3Uri points directly at
the job's job_metadata.json file, not at a folder you have to list. Read
that file first and follow its extraction_path and
custom_path entries to each result.json, rather than
enumerating Amazon S3 keys yourself. See Output location and file structure.
Over-masking with PII detection
Setting PiiEntityTypes to ALL can over-mask form
boilerplate and unlabeled values. Narrow the list to the types you need, and validate
redaction on representative documents. See Detecting and redacting sensitive data.
Supplying ProjectArn and Blueprints
StartDocumentInsights takes exactly one of --project-arn
or --blueprints. Supplying neither returns
ValidationException: Either ProjectArn or
Blueprints must be provided. Inline blueprints produce custom extraction
results only. See Running jobs with inline blueprints.
Unsupported input type
Supported input file types are PDF, PNG, JPEG, and TIFF. See Limits and quotas.