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 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 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 |
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 |
502 UPSTREAM_UNAVAILABLE on every create | Outbound HTTPS blocked | Check egress and the access key. For retries, see 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 |
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 |
| A pending process never advances | Nothing updates it except a GET. Poll it |