Error messages

Learn how to resolve some errors raised by Document AI. This topic discusses errors whose resolutions require more steps than can be easily described in an error message.

See the Cloud API documentation for recommended practices of error handling.

Permissions

Application default credentials are not available

If you receive this message:

The Application Default Credentials are not available. They are
available if running in Google Compute Engine. Otherwise, the
environment variable GOOGLE_APPLICATION_CREDENTIALS must be defined
pointing to a file defining the credentials.
See https://developers.google.com/accounts/docs/application-default-credentials
for more information.

Document AI uses Application Default Credentials for authentication.

You must have a service account for your project, download the key (JSON file) for your service account to your development environment, and then set the location of that JSON file to an environment variable named GOOGLE_APPLICATION_CREDENTIALS.

Furthermore, the GOOGLE_APPLICATION_CREDENTIALS environment variable must be available within the context that you call the Document AI API. For example, if you set the variable from within an terminal session but run your code in the debugger of your IDE, the execution context of your code might not have access to the variable. In that circumtance, your request to Document AI might fail for lack of proper authentication.

For more information on how to set the GOOGLE_APPLICATION_CREDENTIALS environment variable, see the Document AI quickstart or the documentation on using the Application Default Credentials.

Permission denied

If you receive this message:

ERROR: (gcloud.auth.application-default.print-access-token) File /path/to/key.json
(pointed by GOOGLE_APPLICATION_CREDENTIALS environment variable) does not exist!
{
  "error": {
    "code": 403,
    "message": "The request is missing a valid API key.",
    "status": "PERMISSION_DENIED"
  }
}

Verify that you have a valid service account key JSON file in the location stored in the GOOGLE_APPLICATION_CREDENTIALS environment variable and that the variable points to the correct place.

To diagnose this error, try opening the service account key file from the folder from which you're attempting to call the Document AI API.

cat $GOOGLE_APPLICATION_CREDENTIALS

Forbidden: 403 POST API has not been used or is disabled

If you receive the message:

Forbidden: 403 POST Document AI API has not been used in
project # before or it is disabled.
Enable it by visitng [url] then retry.
If you enabled this API recently, wait a few minutes for the action to
propagate and retry.

  1. Visit the link specified in the error message and enable the Document AI API. Wait several minutes and then retry.
  2. Verify that you have a valid service account key JSON file stored in the GOOGLE_APPLICATION_CREDENTIALS environment variable. To diagnose this error, try opening the service account key file from the folder from which you're attempting to call the Document AI API.
    cat $GOOGLE_APPLICATION_CREDENTIALS
    

Error writing final output

If you receive a message like the following when receiving the results of a batch process request:

{
  "name": "projects/project-name/operations/operation-id",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.document.v1beta1.OperationMetadata",
    "state": "SUCCEEDED",
    "createTime": "2019-09-19T02:02:15.885267760Z",
    "updateTime": "2019-09-19T02:02:31.896425001Z"
  },
  "done": true,
  "error": {
    "code": 5,
    "message": "Error writing final output to: gs://bucket-name/filename.json"
  }
}

Your service account may not have the correct permissions to create objects in your Cloud Storage bucket. Be sure that you have assigned the correct permissions to your service account, as described in the quickstart.

You might also have misspelled the name of your Cloud Storage bucket. Verify that the bucket that you're attempting to access exists.

P4SA No Access To Google Cloud Storage

When Document AI Per-Product Service Account (P4SA) has no permission to access some Google Cloud Storage resources.

message: Cloud DocumentAI P4SA doesn't not have access to this Cloud Storage resource:

Invalid arguments

API version unsupported

Example: when a request is made to an API version which does not support the operation.

message: "The requested operation is unsupported for the API version."

Bad Request

When an API request is made but the request fields have one or more violations. Each violation is captured as a field_violations in the google.rpc.BadRequest details.

message: "Request contains an invalid argument."
details {
  [type.googleapis.com/google.rpc.BadRequest] {
    field_violations { field: "foo" description: "bar" }
  }
}

Batch processing all documents failed

When every document in a batch processing request fails to process.

message: "Failed to process all documents."
details {
  [type.googleapis.com/google.rpc.ErrorInfo] {
    reason: "FAILED_TO_PROCESS_ALL_DOCUMENTS"
    domain: "documentai.googleapis.com"
  }
}

The gcsUriPrefix and gcsOutputConfig.gcsUri parameters need to begin with gs:// and end with a trailing backslash character (/). Check the configuration for the Bucket URIs.

Example: gs://bucket/directory/

No documents

When documents are required/expected but none are provided, e.g. importing documents by Cloud Storage URI.

message: "No documents provided."
details {
  [type.googleapis.com/google.rpc.ErrorInfo] {
    reason: "NO_DOCUMENTS"
    domain: "documentai.googleapis.com"
  }
}

No documents selected

When documents are expected but none are selected in the dataset, e.g. creating data labeling jobs.

message: No documents selected. Please select at least one document."
details {
  [type.googleapis.com/google.rpc.ErrorInfo] {
    reason: "NO_DOCUMENTS_SELECTED"
    domain: "documentai.googleapis.com"
  }
}

Document type not found

When a specific document type is expected, but cannot be found in the document.

This may also appear as Couldn't preview the document: Unable to find a document of type: 'foo' in the Google Cloud console.

message: "Unable to find a document of type: 'foo'"
details {
  [type.googleapis.com/google.rpc.ErrorInfo] {
    reason: "DOCUMENT_OF_TYPE_NOT_FOUND"
    domain: "documentai.googleapis.com"
  }
}

Document size limit exceeded

When the upper limit for the file size of a document as been exceeded.

message: "Document size (2) exceeds limit: 1 (bytes)."
details {
  [type.googleapis.com/google.rpc.ErrorInfo] {
    reason: "DOCUMENT_SIZE_LIMIT_EXCEEDED"
    domain: "documentai.googleapis.com"
    metadata { key: "limit" value: "1" }
    metadata { key: "size" value: "2" }
  }
}

Document limit exceeded

When the upper limit for the count of documents has been exceeded.

message: "Document count exceed the limit: 5 got 6"
details {
  [type.googleapis.com/google.rpc.ErrorInfo] {
    reason: "DOCUMENT_LIMIT_EXCEEDED"
    domain: "documentai.googleapis.com"
    metadata { key: "document_limit" value: "5" }
    metadata { key: "documents" value: "6" }
  }
}

Unsupported mime type

When an unsupuported mime type was provided.

message: "Unsupported mime type: 'foo'."
details {
  [type.googleapis.com/google.rpc.ErrorInfo] {
    reason: "UNSUPPORTED_MIME_TYPE"
    domain: "documentai.googleapis.com"
    metadata { key: "mime_type" value: "foo" }
  }
}

No pages

When a document with no pages was provided but is required to have pages.

message: "No pages were found in the document."
details {
  [type.googleapis.com/google.rpc.ErrorInfo] {
    reason: "NO_PAGES"
    domain: "documentai.googleapis.com"
  }
}

Negative page number

When a document lists a negative value for one of its page numbers.

message: "Page number cannot be negative."
details {
  [type.googleapis.com/google.rpc.ErrorInfo] {
    reason: "NEGATIVE_PAGE_NUMBER"
    domain: "documentai.googleapis.com"
  }
}

Duplicate page numbers

When a document lists the same page number one or more times.

message: "Duplicate page number detected (page numbers to indices): [{1, [1, 2]}, {4, [4, 5]}]."
details {
  [type.googleapis.com/google.rpc.ErrorInfo] {
    reason: "DUPLICATE_PAGE_NUMBERS"
    domain: "documentai.googleapis.com"
    metadata {
      key: "page_number_to_indices"
      value: "[{1, [1, 2]}, {4, [4, 5]}]"
    }
  }
}

Page limit exceeded

When the upper limit of a documents total number of pages is exceeded.

message: "Document pages exceed the limit: 5 got 6"
details {
  [type.googleapis.com/google.rpc.ErrorInfo] {
    reason: "PAGE_LIMIT_EXCEEDED"
    domain: "documentai.googleapis.com"
    metadata { key: "page_limit" value: "5" }
    metadata { key: "pages" value: "6" }
  }
}

Pretrained processor version state change

When a request to change the state of a pre-trained processor version was issued.

message: "ProcessorVersion with id 'xyz' is pretrained by Google and cannot change states."
details {
  [type.googleapis.com/google.rpc.ErrorInfo] {
    reason: "PRETRAINED_PROCESSOR_VERSION_STATE_CHANGE"
    domain: "documentai.googleapis.com"
    metadata { key: "processor_id" value: "abc" }
    metadata { key: "target_state" value: "DELETING" }
    metadata { key: "version_id" value: "xyz" }
  }
}

Dataset validation

When a dataset did not meet the validation criteria.

message: "Invalid dataset. See operation metadata for specific errors."
details {
  [type.googleapis.com/google.rpc.ErrorInfo] {
    reason: "INVALID_DATASET"
    domain: "documentai.googleapis.com"
  }
}

Batch processing unsupported

When a batch processing request is issued for a processor which does not support it.

message: "Batch processing is not supported for processor type: 'foo'."
details {
  [type.googleapis.com/google.rpc.ErrorInfo] {
    reason: "BATCH_PROCESSING_UNSUPPORTED"
    domain: "documentai.googleapis.com"
  }
}

Human in the loop non inlined document for review

When a human review was kicked off for a document which was not defined inline.

message: "The document for review must be provided inline."
details {
  [type.googleapis.com/google.rpc.ErrorInfo] {
    reason: "HUMAN_REVIEW_NON_INLINED_DOCUMENT"
    domain: "documentai.googleapis.com"
  }
}

Invalid Document Type

When an invalid document type is referenced.

message: "Invalid document type: 'foo'."
details {
  [type.googleapis.com/google.rpc.ErrorInfo] {
    reason: "INVALID_DOCUMENT_TYPE"
    domain: "documentai.googleapis.com"
    metadata { key: "type" value: "foo" }
  }
}

Document span out of bounds

message: "Text span [1, 5) is out of bounds: [1, 3)."
details {
  [type.googleapis.com/google.rpc.ErrorInfo] {
    reason: "DOCUMENT_SPAN_OUT_OF_BOUNDS"
    domain: "documentai.googleapis.com"
    metadata { key: "bounds" value: "[1, 3)" }
    metadata { key: "span" value: "[1, 5)" }
    metadata { key: "type" value: "Text" }
  }
}

Invalid document span

When an invalid document span (e.g. start is after end) is provided.

message: "Character span is invalid. Ensure the max is greater than the min."
details {
  [type.googleapis.com/google.rpc.ErrorInfo] {
    reason: "DOCUMENT_SPAN_INVALID"
    domain: "documentai.googleapis.com"
    metadata { key: "span" value: "Character" }
  }
}

Invalid UTF-8 document

When a document that includes invalid UTF-8 is provided.

message: "Document contains invalid UTF-8 text."
details {
  [type.googleapis.com/google.rpc.ErrorInfo] {
    reason: "DOCUMENT_INVALID_UTF_8"
    domain: "documentai.googleapis.com"
    metadata { key: "bytes" value: "[2, 3)" }
  }
}

Failed precondition

KMS key invalid

When an invalid key (e.g. it is disabled) was provided.

message: "KMS key 'projects/1/keys/abc' is invalid (KEY_DISABLED)."
details {
  [type.googleapis.com/google.rpc.ErrorInfo] {
    reason: "KMS_KEY_INVALID"
    domain: "documentai.googleapis.com"
    metadata { key: "details" value: "KEY_DISABLED" }
    metadata { key: "kms_key_name" value: "projects/1/keys/abc" }
  }
}

Processor state change

When an invalid request to change the state of a processor is issued.

message: "Processor state cannot be changed to 'DISABLED' since it is 'DISABLED'."
details {
  [type.googleapis.com/google.rpc.ErrorInfo] {
    reason: "PROCESSOR_STATE_CHANGE_INVALID"
    domain: "documentai.googleapis.com"
    metadata { key: "current_state" value: "DISABLED" }
    metadata { key: "processor_id" value: "xyz" }
    metadata { key: "target_state" value: "DISABLED" }
  }
}

Processor version state change

When an invalid request to change the state of a processor version is issued.

message: "ProcessorVersion state cannot be changed to 'DEPLOYING' since it is 'DEPLOYED'."
details {
  [type.googleapis.com/google.rpc.ErrorInfo] {
    reason: "PROCESSOR_VERSION_STATE_CHANGE_INVALID"
    domain: "documentai.googleapis.com"
    metadata { key: "current_state" value: "DEPLOYED" }
    metadata { key: "processor_id" value: "abc" }
    metadata { key: "target_state" value: "DEPLOYING" }
    metadata { key: "version_id" value: "xyz" }
  }
}

Processor not enabled

When a request that depends on a specific processor is issued, but the processor is not enabled.

message: "Processor 'xyz' is not enabled."
details {
  [type.googleapis.com/google.rpc.ErrorInfo] {
    reason: "PROCESSOR_NOT_ENABLED"
    domain: "documentai.googleapis.com"
    metadata { key: "processor_id" value: "xyz" }
    metadata { key: "state" value: "DISABLED" }
  }
}

Processor version not deployed

When a request that depends on a specific processor version being deployed is issued, but the processor is not deployed.

message: "ProcessorVersion 'abc' is not deployed."
details {
  [type.googleapis.com/google.rpc.ErrorInfo] {
    reason: "PROCESSOR_VERSION_NOT_DEPLOYED"
    domain: "documentai.googleapis.com"
    metadata { key: "processor_id" value: "xyz" }
    metadata { key: "state" value: "TRAINING" }
    metadata { key: "version_id" value: "abc" }
  }
}

Processor default version

When a request which depends on a default version being configured is issued but there is not one configured.

message: "Processor 'xyz' does not have a default version configured."
details {
  [type.googleapis.com/google.rpc.ErrorInfo] {
    reason: "PROCESSOR_DEFAULT_VERSION_UNSET"
    domain: "documentai.googleapis.com"
    metadata { key: "processor_id" value: "xyz" }
  }
}

Processor remove default version

When a request to undeploy or delete a processor version is issued but it is currently configured as the default version.

message: "ProcessorVersion 'xyz' cannot be undeployed or deleted as it is the default version."
details {
  [type.googleapis.com/google.rpc.ErrorInfo] {
    reason: "PROCESSOR_REMOVE_DEFAULT_VERSION"
    domain: "documentai.googleapis.com"
    metadata { key: "processor_id" value: "abc" }
    metadata { key: "version_id" value: "xyz" }
  }
}

Dataset not initialized

When a request that requires a dataset to be initialized is issued, but the dataset is not initialized.

message: "Dataset is not initialized."
details {
  [type.googleapis.com/google.rpc.ErrorInfo] {
    reason: "DATASET_NOT_INITIALIZED"
    domain: "documentai.googleapis.com"
  }
}

Not found

Evaluation not found

When an evaluation for a processor version cannot be found.

message: "Evaluation with ID 'qrs' not found."
details {
  [type.googleapis.com/google.rpc.ErrorInfo] {
    reason: "EVALUATION_NOT_FOUND"
    domain: "documentai.googleapis.com"
    metadata { key: "evaluation_id" value: "qrs" }
    metadata { key: "processor_id" value: "xyz" }
    metadata { key: "version_id" value: "abc" }
  }
}

Document not found

When a document needed for an operation cannot be found.

message: "Document not found: 'gs://foo'."
details {
  [type.googleapis.com/google.rpc.ErrorInfo] {
    reason: "DOCUMENT_NOT_FOUND"
    domain: "documentai.googleapis.com"
    metadata { key: "document" value: "gs://foo" }
  }
}

Processor not found

When a processor needed for an operation cannot be found.

message: "Processor with id 'xyz' not found."
details {
  [type.googleapis.com/google.rpc.ErrorInfo] {
    reason: "PROCESSOR_NOT_FOUND"
    domain: "documentai.googleapis.com"
    metadata { key: "processor_id" value: "xyz" }
  }
}

Processor version not found

When a processor version needed for an operation cannot be found.

message: "ProcessorVersion with id 'abc' not found."
details {
  [type.googleapis.com/google.rpc.ErrorInfo] {
    reason: "PROCESSOR_VERSION_NOT_FOUND"
    domain: "documentai.googleapis.com"
    metadata { key: "processor_id" value: "xyz" }
    metadata { key: "version_id" value: "abc" }
  }
}

Quotas and limits

Quota exceeded

If you receive this message:

RESOURCE_EXHAUSTED: Quota exceeded.

You have reached the limit of your per-minute or daily quota. Review the quotas & limits for using Document AI.

You can request an increase to your quotas from the Google Cloud console.

Outages & Latency

Timeouts

Operation did not complete within the designated timeout.

If you receive the following (or similar) error messages when polling a Long-Running Operation (LRO):

google.api_core.future.polling._OperationNotComplete
...
google.api_core.exceptions.RetryError: Deadline of 0.0s exceeded while calling target function, last exception:
...
concurrent.futures._base.TimeoutError: Operation did not complete within the designated timeout.

Then the user-set timeout value for completion of the operation is set too low for the document being processed. This error does not indicate that the batch process operation failed, the operation will continue regardless of the user-set timeout value.