---
title: 故障排查
description: Human Plugin 中的启动失败、错误响应和意外结果，以及每种情况的原因和解决办法。
canonical: https://developer.unico.io/zh-CN/human-plugin/additional-resources/troubleshooting
locale: zh-CN
generated_by: markdown-export
---

# 故障排查

症状、原因和处理方法。

## 容器无法启动

| 日志消息（摘要） | 原因 | 解决办法 |
| --- | --- | --- |
| Reading config | 缺少 `POSTGRES_ADDRESS_HOST`、`POSTGRES_PASSWORD` 或 `HUMAN_API_ACCESS_KEY`，或其值为空 | 设置该变量 |
| `POSTGRES_PASSWORD must not contain…` | 包含空白字符、引号、反斜杠或控制字符 | 更换密码 |
| 错误中指明的任何其他变量 | 设置了[受支持的配置](/zh-CN/human-plugin/self-hosting/configuration)之外的变量 | 移除该变量 |
| Downloading attribute catalog | 对 `human-token-assets.unico.app` 的出站访问被阻止，或 10 秒内没有响应 | 允许出站 HTTPS 访问该地址 |
| `database "…" does not exist` | `POSTGRES_DATABASE` 中指定的数据库（默认为 `human_plugin`）尚未创建 | 创建该数据库，或将 `POSTGRES_DATABASE` 设置为您已创建的数据库 |
| Connecting to or preparing the database | PostgreSQL 无法访问、凭据或 SSL 模式错误，或该角色无法创建表 | 检查[数据库连接](/zh-CN/human-plugin/self-hosting/configuration#database-connection)和该角色的权限 |

## 请求

| 症状 | 原因 | 解决办法 |
| --- | --- | --- |
| `401`，响应为 `{"message":"","details":[]}` | Unico 拒绝了访问密钥：缺失、错误或已失效 | 检查 `HUMAN_API_ACCESS_KEY` 并重启 Human Plugin。如果密钥无误，请联系 Unico 确认其已启用 |
| `400 MISSING_CREDENTIAL_TYPE` | 缺少 `credential`，或其为包含空字符串的对象 | 发送证件，或发送 `null` / `{}` |
| `400 INVALID_REQUEST`，但请求体看起来有效 | 使用了 Human Plugin 保留的字段、`clientId`、`correlationId` 或 `credential` 的其他拼写（如 `client_id`），或其中某个字段的值不是字符串 | 使用[创建流程](/zh-CN/human-plugin/api-reference/create-process)中的准确字段名 |
| `400 INVALID_CLIENT_ID`（或其他字段） | 超出字节限制、包含控制字符，或首尾有空白 | 去除空白并缩短 |
| `400 REQUEST_TOO_LARGE` | 请求体超过 2 MiB | 减小图像大小 |
| `409 CORRELATION_ID_ALREADY_USED` | 已有其他流程使用该 `correlationId`，包括失败的流程 | 发送新的、唯一的 `correlationId` |
| `422 ATTRIBUTE_TYPE_NOT_SUPPORTED` | 代码不在目录中，或大小写错误 | 使用目录中的准确代码 |
| `4xx`，`message` 不熟悉 | 流程拒绝了请求：涉及流程、图像或流程字段 | 参见[拒绝情形](/zh-CN/human-plugin/api-reference/create-process#flow-refusals) |
| 每次创建都返回 `502 UPSTREAM_UNAVAILABLE` | 出站 HTTPS 被阻止 | 检查[出站访问](/zh-CN/human-plugin/self-hosting/networking-and-security)和访问密钥。关于重试，参见[错误与重试](/zh-CN/human-plugin/api-reference/errors-and-retries) |
| `503 DATABASE_UNAVAILABLE` | PostgreSQL 无法访问 | 检查数据库。就绪检查也会失败 |
| 已知流程返回 `404 PROCESS_NOT_FOUND` | 安装实例或数据库错误，或 id 格式不正确 | 确认 id 以及您调用的是哪个 Human Plugin |

## 结果

| 症状 | 原因 |
| --- | --- |
| `PROCESS_STATE_FINISHED`，但此人未匹配 | Finished 也包含否定结果。请读取 `data` |
| 缺少 `data.ndocs` | 未完成、非活体采集、匹配为否定，或无法计算情报。请重新读取。参见[情报](/zh-CN/human-plugin/get-started/intelligence) |
| `GET` 中缺少 Journey 的 `token` / `link` | 它们仅在创建时返回 |
| `PROCESS_STATE_FAILED` 且 `data: {}` | 流程结束时没有结果。参见[流程生命周期](/zh-CN/human-plugin/api-reference/process-lifecycle) |
| 待处理的流程始终没有推进 | 只有 `GET` 才会更新它。请轮询 |