---
title: 문제 해결
description: Human Plugin의 시작 실패, 오류 응답, 예상과 다른 결과를 원인과 해결 방법과 함께 설명합니다.
canonical: https://developer.unico.io/ko/human-plugin/additional-resources/troubleshooting
locale: ko
generated_by: markdown-export
---

# 문제 해결

증상, 원인, 조치 방법.

## 컨테이너가 시작되지 않는 경우

| 로그 메시지(요약) | 원인 | 해결 방법 |
| --- | --- | --- |
| Reading config | `POSTGRES_ADDRESS_HOST`, `POSTGRES_PASSWORD` 또는 `HUMAN_API_ACCESS_KEY`가 없거나 비어 있음 | 값을 설정하세요 |
| `POSTGRES_PASSWORD must not contain…` | 공백, 따옴표, 백슬래시 또는 제어 문자가 포함됨 | 다른 비밀번호를 사용하세요 |
| 오류에 명시된 그 외 변수 | [지원되는 구성](/ko/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 모드 오류, 또는 역할에 테이블 생성 권한이 없음 | [데이터베이스 연결](/ko/human-plugin/self-hosting/configuration#database-connection)과 역할의 권한을 확인하세요 |

## 요청

| 증상 | 원인 | 해결 방법 |
| --- | --- | --- |
| `{"message":"","details":[]}`와 함께 `401` | Unico가 액세스 키를 거부함: 누락, 오류 또는 더 이상 유효하지 않음 | `HUMAN_API_ACCESS_KEY`를 확인하고 Human Plugin을 재시작하세요. 키가 맞다면 Unico에 활성화 여부를 확인해 달라고 요청하세요 |
| `400 MISSING_CREDENTIAL_TYPE` | `credential`이 없거나 빈 문자열로 된 객체임 | 문서를 보내거나 `null` / `{}`를 보내세요 |
| 올바른 것처럼 보이는 본문인데 `400 INVALID_REQUEST` | Human Plugin이 예약한 필드, `clientId`, `correlationId`, `credential`의 다른 표기(예: `client_id`), 또는 이 필드 중 하나에 문자열이 아닌 값을 보냄 | [프로세스 생성](/ko/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` | 코드가 카탈로그에 없거나 대소문자가 다름 | 카탈로그의 정확한 코드를 사용하세요 |
| 낯선 `message`가 포함된 `4xx` | 플로우가 요청을 거부함: 플로우, 이미지 또는 플로우 필드 문제 | [거부 사유](/ko/human-plugin/api-reference/create-process#flow-refusals)를 참고하세요 |
| 모든 생성 요청에서 `502 UPSTREAM_UNAVAILABLE` | 아웃바운드 HTTPS가 차단됨 | [이그레스](/ko/human-plugin/self-hosting/networking-and-security)와 액세스 키를 확인하세요. 재시도는 [오류 및 재시도](/ko/human-plugin/api-reference/errors-and-retries)를 참고하세요 |
| `503 DATABASE_UNAVAILABLE` | PostgreSQL에 연결할 수 없음 | 데이터베이스를 확인하세요. 준비 상태(readiness) 확인도 실패합니다 |
| 알려진 프로세스인데 `404 PROCESS_NOT_FOUND` | 설치 또는 데이터베이스가 잘못되었거나 id 형식이 올바르지 않음 | id와 호출 중인 Human Plugin을 확인하세요 |

## 결과

| 증상 | 원인 |
| --- | --- |
| `PROCESS_STATE_FINISHED`인데 본인이 일치하지 않음 | 완료(Finished)에는 부정적인 결과도 포함됩니다. `data`를 확인하세요 |
| `data.ndocs`가 없음 | 완료되지 않았거나, 라이브가 아닌 캡처이거나, 불일치 결과이거나, 인텔리전스를 계산하지 못함. 다시 조회하세요. [인텔리전스](/ko/human-plugin/get-started/intelligence)를 참고하세요 |
| `GET`에서 Journey `token` / `link`가 없음 | 생성 시에만 반환됩니다 |
| `data: {}`와 함께 `PROCESS_STATE_FAILED` | 프로세스가 결과 없이 종료되었습니다. [프로세스 수명 주기](/ko/human-plugin/api-reference/process-lifecycle)를 참고하세요 |
| 대기 중인 프로세스가 진행되지 않음 | `GET` 외에는 프로세스를 갱신하는 것이 없습니다. 폴링하세요 |