此页面由 Cloud Translation API 翻译。

错误消息

了解如何解决 Document AI 引发的一些错误。本主题讨论解决方法需要多个步骤且无法在错误消息中说明的错误。

如需了解错误处理的推荐做法，请参阅 Cloud API 文档。

权限

解决方法需要执行几个步骤，如错误消息中所述。

应用默认凭据不可用

如果收到此消息：

The Application Default Credentials are not available. They are
available if running in 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 使用应用默认凭据执行身份验证。

您必须拥有项目的服务账号，并将服务账号的密钥（JSON 文件）下载到开发环境，然后将该 JSON 文件的位置设置成名为 GOOGLE_APPLICATION_CREDENTIALS 的环境变量。

此外，GOOGLE_APPLICATION_CREDENTIALS 环境变量必须在您调用 Document AI API 的上下文中可用。例如，如果您在终端会话中设置变量但在 IDE 的调试程序中运行代码，则代码的执行上下文可能无法访问该变量。在这种情况下，对 Document AI 发出的请求可能因未经过适当的身份验证而失败。

如需详细了解如何设置 GOOGLE_APPLICATION_CREDENTIALS 环境变量，请参阅 Document AI 快速入门或有关使用应用默认凭据的文档。

权限遭拒

如果收到此消息：

ERROR: (gcloud.auth.application-default.print-access-token) File
(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"
  }
}

确认 GOOGLE_APPLICATION_CREDENTIALS 环境变量中存储的位置中包含有效的服务账号密钥 JSON 文件，并且该变量指向正确的位置。

如需诊断此错误，请尝试从您尝试调用 Document AI API 的文件夹中打开服务账号密钥文件。

cat $GOOGLE_APPLICATION_CREDENTIALS

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

如果您收到此消息：

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

访问错误消息中指定的链接，并启用 Document AI API。等待几分钟，然后重试。
验证您是否在 GOOGLE_APPLICATION_CREDENTIALS 环境变量中存储了有效的服务账号密钥 JSON 文件。如需诊断此错误，请尝试从您尝试调用 Document AI API 的文件夹中打开服务账号密钥文件。
```
cat $GOOGLE_APPLICATION_CREDENTIALS
```

写入最终输出时出错

如果您在收到批量处理请求的结果时收到如下消息：

{
  "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"
  }
}

您的服务账号可能没有在 Cloud Storage 存储分区中创建对象的正确权限。请确保您已向服务账号分配了正确的权限，如快速入门中所述。

您也可能拼错了 Cloud Storage 存储分区的名称。验证您尝试访问的存储分区是否存在。

P4SA 无权访问 Cloud Storage

Document AI 产品专属服务账号 (P4SA) 无权访问某些 Cloud Storage 资源。

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

服务账号无法在 Cloud Storage 中创建对象

Document AI 产品级服务账号 (P4SA) 无权在 Cloud Storage 中创建对象。

message: Service account service-123@gcp-sa-prod-dai-core.iam.gserviceaccount.com
         does not have permission storage.objects.create to create
         Google Cloud Storage object in bucket gs://foo.

Document AI 服务账号可能没有在您的 Cloud Storage 存储分区中创建对象的正确权限。请确保您已向 Document AI 服务账号分配了正确的权限，如跨项目文件访问权限设置中所述。

您也可能拼错了 Cloud Storage 存储分区的名称。验证您尝试访问的存储分区是否存在。

调用方无法获取 Cloud Storage 中的对象

Document AI API 的调用方无权获取 Cloud Storage 中的对象。

message: The caller does not have permission storage.objects.get to get Google
         Cloud Storage objects in bucket gs://foo.

API 的调用方可能没有获取 Cloud Storage 存储分区中对象的正确权限。请确保您已向调用方分配正确的权限。

您也可能拼错了 Cloud Storage 存储分区的名称。验证您尝试访问的存储分区是否存在。

参数无效

解决方法需要执行几个步骤，如错误消息中所述。

不支持的 API 版本

示例：向不支持相应操作的 API 版本发出请求。

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

Bad Request

发出 API 请求，但请求字段存在一个或多个违规问题。每个违规行为都会在 google.rpc.BadRequest 详情中捕获为 field_violations。

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

批量处理所有文档失败

批量处理请求中的每份文档都无法处理。

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

没有文档

系统要求或预期提供文档，但未提供任何文档，例如通过 Cloud Storage URI 导入文档时。

message: "No valid documents found in ${training|test} directory. Ensure files are in a supported MIME type. For details, see https://cloud.google.com/document-ai/docs/file-types."
details {
  [type.googleapis.com/google.rpc.ErrorInfo] {
    reason: "NO_DOCUMENTS"
    domain: "documentai.googleapis.com"
  }
}

gcsUriPrefix 和 gcsOutputConfig.gcsUri 参数需要以 gs:// 开头，并以尾部反斜杠字符 (/) 结尾。请检查存储分区 URI 的配置。

示例：gs://bucket/directory/

不支持训练

针对不支持训练的处理器类型发出序列处理器版本请求时。

message: "Training is not supported on processor type: ${DOCUMENT_TYPE}_PROCESSOR."

未选择任何文档

预期有文档，但数据集中未选择任何文档，例如在创建数据标注作业时。

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"
  }
}

未找到文档类型

当证件类别（例如驾照、护照或账单）与处理器类型所需的分类不符时。例如，W2 解析器中的分类器步骤未找到账单中的元素。

这在 Google Cloud 控制台中也可能显示为 Couldn't preview the document: Unable to find a document of type: 'foo'。此错误消息适用于旧版处理器。

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"
  }
}

文档大小超出限制

在导入数据集或运行预测时，文档的文件大小超出了上限。

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" }
  }
}

已超出文档数上限

文档数量超出上限时。

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" }
  }
}

不支持的 MIME 类型

提供的 MIME 类型不受支持。在您导入数据集和进行预测调用时，系统会验证文件格式（MIME 类型）。如果文件格式不受支持，您会看到以下错误消息：

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" }
  }
}

文档 MIME 类型不正确

当文档内容与指定的 MIME 类型不匹配时。在您导入数据集和进行预测调用时，系统会验证文件格式（MIME 类型）。如果您提供的文件格式与预期格式不符，您会看到以下错误消息：

message: "Incorrect document content for mime_type: foo"
details {
  [type.googleapis.com/google.rpc.ErrorInfo] {
    reason: "INCORRECT_DOCUMENT_MIME_TYPE"
    domain: "documentai.googleapis.com"
    metadata { key: "mime_type" value: "foo" }
  }
}

无页面

提供的文档没有页面，但需要提供一个或多个页面。

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

负页码

文档为其页码之一列出了负值。

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

页码重复

文档中列出了同一页码一次或多次。

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]}]"
    }
  }
}

超出页面数量上限

文档的总页数超出上限。如果数据集中的文档页数过多，超出了处理器的限制，您在数据集导入或预测期间就会遇到此错误。

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" }
  }
}

预训练处理器版本状态更改

发出更改预训练处理器版本状态的请求时。您在尝试删除预训练的处理器版本时遇到此错误。

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" }
  }
}

数据集验证

当数据集不符合验证条件时（例如，由于网页锚点缺失、数据不正确或文档 proto 对象的某些属性中缺少详细信息），就会出现此错误。

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

人机协同非内嵌文档以供审核

系统针对未内嵌定义的文档启动人工审核时。

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"
  }
}

文件类型无效

引用文件格式不受支持或格式有误的文件时（例如 .mp4.）

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" }
  }
}

文档超出边界

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" }
  }
}

文档片段无效

提供无效的文档片段（例如，开始时间晚于结束时间）。

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" }
  }
}

UTF-8 文档无效

提供包含无效 UTF-8 的文档时。

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)" }
  }
}

数据集架构无效

处理器没有有效的联合架构，或者给定的数据集架构无效。

message: "The processor has an empty or invalid schema: "
details {
  [type.googleapis.com/google.rpc.ErrorInfo] {
    reason: "INVALID_SCHEMA_ERROR"
    domain: "documentai.googleapis.com"
  }
}

OcrConfig 不受支持

针对不支持 OcrConfig 的处理器发出处理请求时。

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

导入配置无效

导入配置无效时。

message: "The import config is invalid: foo"
details {
  [type.googleapis.com/google.rpc.ErrorInfo] {
    reason: "INVALID_IMPORT_CONFIG"
    domain: "documentai.googleapis.com"
  }
}

来源处理器版本无效

尝试导入处理器版本时，源处理器版本无效，无法导入。

message: "The source processor version is invalid in import processor version."
details {
  [type.googleapis.com/google.rpc.ErrorInfo] {
    reason: "INVALID_SOURCE_PROCESSOR_VERSION_ERROR"
    domain: "documentai.googleapis.com"
  }
}

Failed precondition

解决方法需要执行几个步骤，如错误消息中所述。

KMS 密钥无效

提供的密钥无效（例如已停用）。

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" }
  }
}

处理器状态更改

发出更改处理器状态的无效请求时。

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" }
  }
}

处理器版本状态更改

发出更改处理器版本状态的无效请求时。

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" }
  }
}

未启用处理器

发出依赖于特定处理器的请求，但该处理器未启用。

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" }
  }
}

未部署处理器版本

发出依赖于正在部署的特定处理器版本的请求，但未部署该处理器。

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" }
  }
}

处理器默认版本

发出依赖于正在配置的默认版本的请求，但未配置任何默认版本。

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" }
  }
}

处理器移除默认版本

发出取消部署或删除处理器版本的请求，但该版本已配置为默认版本。

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" }
  }
}

数据集未初始化

发出需要初始化数据集的请求，但数据集未初始化。

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

数据集已初始化或正在初始化

发出要求数据集未初始化的请求，但数据集已初始化或正在初始化。

message: "Dataset is already initialized or is initializing."
details {
  [type.googleapis.com/google.rpc.ErrorInfo] {
    reason: "DATASET_INITIALIZED_OR_INITIALIZING"
    domain: "documentai.googleapis.com"
  }
}

数据集位置不为空错误

请求要求数据集存储位置为空，但文件夹包含对象。

message: "Given dataset location is not empty. Please select an empty folder."
details {
  [type.googleapis.com/google.rpc.ErrorInfo] {
    reason: "DATASET_LOCATION_NOT_EMPTY"
    domain: "documentai.googleapis.com"
  }
}

存在屏蔽操作错误

有其他正在运行的操作阻塞了所需的操作。

message: "The operation cannot be performed due to an ongoing 'EXAMPLE_OPERATION_TYPE' blocking operation. Try again after the operation finishes."
details {
  [type.googleapis.com/google.rpc.ErrorInfo] {
    reason: "HAS_BLOCKING_OPERATION_ERROR"
    domain: "documentai.googleapis.com"
  }
}

“不支持页面范围”错误

某些操作（例如批处理）不支持 page_range 字段。

message: "Page range is not supported."
details {
  [type.googleapis.com/google.rpc.ErrorInfo] {
    reason: "PAGE_RANGE_UNSUPPORTED"
    domain: "documentai.googleapis.com"
  }
}

Cloud Storage 文件夹包含数据集错误

Cloud Storage 文件夹中已包含数据集。

message:  "The folder 'folder_uri' already has dataset 'dataset-id' under it."
details {
   [type.googleapis.com/google.rpc.ErrorInfo] {
     reason: "GCS_FOLDER_CONTAINS_DATASET_ERROR"
     domain: "documentai.googleapis.com"
   }
}

缩略图缺失错误

当数据集文档缩略图提取失败时。

message:  "Failed to get dataset document thumbnail, consider running re-sync on the dataset."
details {
   [type.googleapis.com/google.rpc.ErrorInfo] {
     reason: "THUMBNAIL_MISSING"
     domain: "documentai.googleapis.com"
   }
}

超出数据集页面数上限

当数据集的总页面数超出上限时。

message: "Dataset page count exceeds the limit of 5. Got 6."
details {
  [type.googleapis.com/google.rpc.ErrorInfo] {
    reason: "DATASET_PAGE_LIMIT_EXCEEDED"
    domain: "documentai.googleapis.com"
  }
}

未找到

解决方法需要执行几个步骤，如错误消息中所述。

未找到评估

找不到处理器版本的评估结果时。

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" }
  }
}

找不到文档

找不到操作所需的文档。

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" }
  }
}

找不到处理器

找不到操作所需的处理器。

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" }
  }
}

未找到处理器版本

找不到操作所需的处理器版本。

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" }
  }
}

找不到为数据加标签的作业

找不到数据标签作业时。

message: "Data labeling job with id 'EXAMPLE_DATA_LABELING_JOB' not found in processor EXAMPLE_PROCESSOR."

已存在

解决方法需要执行几个步骤，如错误消息中所述。

人机协同标注工具已存在

创建已存在的标签添加者池。

message: "The labeler pool already exists."

配额和限制

解决方法需要执行几个步骤，如错误消息中所述。

已超出配额

如果收到此消息：

RESOURCE_EXHAUSTED: Quota exceeded.

您已达到每分钟或每日配额的上限。请查看使用 Document AI 的配额和限制。

您可以通过 Google Cloud Console 申请增加配额。

服务中断和延迟

解决方法需要执行几个步骤，如错误消息中所述。

超时

对于在线处理，服务器端对请求设置了 2 分钟的超时时间。
对于批量处理，生成长时间运行的操作时，服务器端存在 2 分钟的超时，但批量作业的完成没有超时。
- 如需了解详情，请参阅长时间运行的操作文档。

操作未在指定的超时期限内完成。

如果您在轮询长时间运行的操作 (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.

然后，用户为操作完成设置的超时值对于正在处理的文档而言设置得过低。此错误不表示批处理操作失败，无论用户设置的超时值如何，操作都会继续。

获取支持

弃用