---
title: Troubleshooting
description: Startup failures, error responses and unexpected results in Human Plugin, with the cause and the fix for each.
canonical: https://developer.unico.io/human-plugin/additional-resources/troubleshooting
locale: en
generated_by: markdown-export
---

# Troubleshooting

Symptom, cause and what to do.

## The container does not start

| Log message (summary) | Cause | Fix |
| --- | --- | --- |
| Reading config | `POSTGRES_ADDRESS_HOST`, `POSTGRES_PASSWORD` or `HUMAN_API_ACCESS_KEY` is missing or empty | Set it |
| `POSTGRES_PASSWORD must not contain…` | Whitespace, quote, backslash or control characters | Use another password |
| Any other variable named in the error | A variable outside the [supported configuration](/human-plugin/self-hosting/configuration) was set | Remove it |
| Downloading attribute catalog | Egress to `human-token-assets.unico.app` blocked, or no answer within 10 seconds | Allow outbound HTTPS to it |
| `database "…" does not exist` | The database named in `POSTGRES_DATABASE`, `human_plugin` by default, was not created | Create the database, or set `POSTGRES_DATABASE` to the one you created |
| Connecting to or preparing the database | PostgreSQL unreachable, wrong credentials or SSL mode, or the role cannot create tables | Check the [database connection](/human-plugin/self-hosting/configuration#database-connection) and the role's permissions |

## Requests

| Symptom | Cause | Fix |
| --- | --- | --- |
| `401` with `{"message":"","details":[]}` | Unico refused the access key: missing, wrong, or no longer valid | Check `HUMAN_API_ACCESS_KEY` and restart Human Plugin. If the key is right, ask Unico to confirm it is enabled |
| `400 MISSING_CREDENTIAL_TYPE` | `credential` is missing, or an object with empty strings | Send a document, or `null` / `{}` |
| `400 INVALID_REQUEST` with a valid-looking body | A field Human Plugin reserves, another spelling of `clientId`, `correlationId` or `credential` (such as `client_id`), or a non-string value in one of them | Use the exact field names from [Create a process](/human-plugin/api-reference/create-process) |
| `400 INVALID_CLIENT_ID` (or another field) | Over the byte limit, control characters, or surrounding whitespace | Trim and shorten |
| `400 REQUEST_TOO_LARGE` | Body over 2 MiB | Reduce the image size |
| `409 CORRELATION_ID_ALREADY_USED` | Another process already has that `correlationId`, a failed one included | Send a new, unique `correlationId` |
| `422 ATTRIBUTE_TYPE_NOT_SUPPORTED` | Code not in the catalog, or wrong case | Use an exact code from the catalog |
| `4xx` with an unfamiliar `message` | The flow refused the request: the flow, the image or a flow field | See [Refusals](/human-plugin/api-reference/create-process#flow-refusals) |
| `502 UPSTREAM_UNAVAILABLE` on every create | Outbound HTTPS blocked | Check [egress](/human-plugin/self-hosting/networking-and-security) and the access key. For retries, see [Errors and retries](/human-plugin/api-reference/errors-and-retries) |
| `503 DATABASE_UNAVAILABLE` | PostgreSQL unreachable | Check the database. Readiness also fails |
| `404 PROCESS_NOT_FOUND` for a known process | Wrong installation or database, or a malformed id | Confirm the id and which Human Plugin you call |

## Results

| Symptom | Cause |
| --- | --- |
| `PROCESS_STATE_FINISHED` but the person did not match | Finished includes a negative outcome. Read `data` |
| `data.ndocs` missing | Not finished, a non-live capture, a negative match, or the intelligence could not be computed. Read again. See [Intelligence](/human-plugin/get-started/intelligence) |
| Journey `token` / `link` missing on `GET` | They are returned only on create |
| `PROCESS_STATE_FAILED` with `data: {}` | The process ended without a result. See [Process lifecycle](/human-plugin/api-reference/process-lifecycle) |
| A pending process never advances | Nothing updates it except a `GET`. Poll it |