> ## Documentation Index
> Fetch the complete documentation index at: https://docs.get-clara.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# 가져오기 오류 해결

> CSV 가져오기 오류를 해결하기 위한 종합적인 문제 해결 가이드.

## 개요

가져오기가 안 되나요? 이 가이드는 일반적인 가져오기 오류를 단계별로 식별하고 해결하도록 도와줍니다.

## 가져오기 유효성 검사가 작동하는 방식

파일을 업로드하고 열을 매핑한 후, Twenty가 데이터에 대해 유효성 검사를 수행합니다:

1. **유효성 검사를 실행** — Twenty가 각 행에서 오류를 확인합니다
2. **오류가 강조 표시됨** — 문제가 있는 행은 **노란색**으로 표시됩니다
3. **바로 수정 가능** — 가져오기 UI에서 셀을 직접 편집합니다
4. **또는 행을 제거** — 문제가 있는 레코드를 완전히 건너뜁니다

<Note>**UI에서 오류를 수정하세요.** 스프레드시트로 돌아갈 필요가 없습니다. 가져오는 동안 셀을 직접 편집하여 시간을 절약하세요.</Note>

## 단계별 문제 해결

### 1단계: 오류 유형 식별

강조 표시된 행을 클릭하여 특정 오류 메시지를 확인하세요. 일반적인 오류 유형:

| 오류 메시지                                                           | 의미                                |
| ---------------------------------------------------------------- | --------------------------------- |
| 중복 값이 노란색으로 강조 표시됨                                               | 값이 Twenty에 이미 존재하거나 파일에 두 번 나타납니다 |
| `{field} is not a valid {type}` (노란색 셀에 커서를 올리세요)                | 데이터가 예상 형식과 일치하지 않음               |
| 필수 필드가 강조 표시됨                                                    | 필수 필드가 비어 있음                      |
| `Can't connect to {object}. No unique record found...` (가져오기 실패) | 참조된 레코드가 존재하지 않음                  |
| `Too many records. Up to 10000 allowed` (업로드 차단됨)                | 파일의 레코드가 10,000개를 초과함             |

### 2단계: 오류 수정

오류 유형별로 아래의 구체적인 지침을 따르세요.

***

## 오류: 중복 값

### 볼 수 있는 내용

가져오기를 시작하기 전에 가져오기 UI에서 중복 값이 있는 행이 **노란색으로 강조 표시**됩니다.

### 의미

고유 필드(이메일, 도메인)가 다음에 해당함:

* Twenty에 이미 존재함
* 파일에 두 번 나타남

### 해결 방법

**옵션 1: 중복 값을 편집**

1. 오류가 있는 셀을 클릭
2. 고유 값으로 변경
3. 가져오기를 계속

**옵션 2: 중복 행 제거**

1. 행 옆의 X를 클릭
2. 해당 행은 가져오기 중에 건너뜁니다

**옵션 3: Twenty로 기존 레코드를 업데이트**

1. 파일에 고유 식별자(`email`, `domain`, 또는 `id`)가 포함되어 있는지 확인하세요
2. 고유 식별자 필드를 매핑하세요
3. Twenty가 중복을 생성하는 대신 기존 레코드를 업데이트합니다

<Note>
  **고유 필드도 업데이트할 수 있습니다.**

  * `id`는 유지하고 `email`만 변경하면 → 이메일이 업데이트됩니다
  * `email`은 유지하고 `id`만 변경하면 → id가 업데이트됩니다

  하나의 고유 식별자만 일치해도 Twenty가 레코드를 업데이트합니다.
</Note>

### 이 오류를 방지하는 방법

가져오기 전:

1. 스프레드시트를 고유 필드로 정렬
2. 중복 행 제거
3. 레코드가 Twenty에 이미 존재하는지 확인

<Warning>
  **소프트 삭제된 레코드도 고유성에 포함됩니다.**

  Command 메뉴 → 삭제된 레코드 보기를 확인하세요. 그곳의 레코드도 여전히 고유성을 강제합니다. 완전히 삭제하거나 복원한 뒤 업데이트하세요.
</Warning>

자세한 내용: [고유성 제약 조건](/l/ko/user-guide/data-migration/capabilities/uniqueness-constraints)

***

## 오류: 잘못된 형식

### 볼 수 있는 내용

셀 값이 노란색으로 강조 표시됩니다. 해당 부분에 커서를 올리면 오류 메시지가 표시됩니다:

```
{field name} is not a valid {field type}
```

### 의미

데이터가 해당 필드 유형의 예상 형식과 일치하지 않습니다.

### 해결 방법 — 필드 유형별

#### 이메일

**문제:** 잘못된 이메일 형식
**해결:** `name@domain.com` 형식을 사용하세요

```
❌ john.smith@
❌ john smith@acme.com
✓ john.smith@acme.com
```

#### 도메인

**문제:** 일관되지 않은 형식은 중복을 유발할 수 있음
**해결:** `https://domain.com` 형식을 사용하세요(권장)

```
⚠️ acme.com         (valid, but not recommended)
⚠️ www.acme.com     (valid, but not recommended)
✅ https://acme.com  (recommended)
```

<Note>모든 형식이 유효하지만 `https://domain.com`은 이메일/캘린더 동기화에서 사용하는 형식과 일치하므로 권장됩니다. 다른 형식을 사용하면 회사가 중복으로 생성될 수 있습니다.</Note>

#### 날짜

**문제:** 인식되지 않는 날짜 형식
**해결:** 파일 전체에서 일관된 형식을 사용하세요

```
✓ 2024-03-15        (YYYY-MM-DD - recommended)
✓ 03/15/2024        (MM/DD/YYYY)
✓ 15/03/2024        (DD/MM/YYYY)
```

#### 전화

**문제:** 필수 열 누락
**해결:** 모든 전화 열을 포함하세요

| 열                                       | 예시           |
| --------------------------------------- | ------------ |
| **Phones / Primary Phone Number**       | `4159095555` |
| **Phones / Primary Phone Country Code** | `US`         |
| **Phones / Primary Phone Calling Code** | `+1`         |

#### 부울

**문제:** 잘못된 불리언 값
**해결:** 대문자 `TRUE` 또는 `FALSE`를 사용하세요

```
❌ true
❌ yes
❌ 1
✓ TRUE
✓ FALSE
```

#### 선택 / 다중 선택

**문제:** 값이 기존 옵션과 일치하지 않음
**해결:** 표시 라벨이 아니라 **API 이름**을 사용하세요

API 이름을 찾는 방법:

1. **설정 → 데이터 모델**로 이동
2. 객체와 필드를 선택하세요
3. **고급 모드**를 활성화하세요(오른쪽 하단 토글)
4. API 이름을 사용하세요(예: `OPTION_1`, "Option 1" 아님)

```
❌ High Priority
✓ HIGH_PRIORITY
```

#### 통화

**문제:** 금액 또는 통화 코드 누락
**해결:** 두 열 모두 채우세요

| 열                     | 예시        |
| --------------------- | --------- |
| **Amount / Amount**   | `1234.56` |
| **Amount / Currency** | `USD`     |

#### 숫자

**문제:** 숫자가 아닌 문자 포함
**해결:** 숫자만 사용하고 소수점은 점(.)을 사용하세요

```
❌ $1,234.56
❌ 1,234.56
✓ 1234.56
```

전체 형식 참고: [필드 매핑](/l/ko/user-guide/data-migration/capabilities/field-mapping)

***

## 오류: 필수 필드 누락

### 볼 수 있는 내용

해당 행이 노란색으로 강조 표시되고 필수 필드 셀이 표시됩니다.

### 의미

이 행의 필수 필드가 비어 있습니다.

### 해결 방법

**옵션 1: 값 입력**

1. 빈 셀을 클릭
2. 값 입력
3. 가져오기를 계속

**옵션 2: 행 제거**

1. 데이터가 없다면 X를 클릭해 해당 행을 건너뛰세요

### 이 오류를 방지하는 방법

가져오기 전에 필수 필드를 확인하세요:

1. **설정 → 데이터 모델**로 이동
2. 객체를 선택하세요
3. 어떤 필드가 필수로 표시되어 있는지 확인하세요

***

## 오류: 관계를 찾을 수 없음

### 볼 수 있는 내용

이 오류는 **가져오기가 시작된 후** 나타나며, 다음과 같은 메시지와 함께 가져오기가 실패합니다:

```
Can't connect to company. No unique record found with condition: id = 7776ee49-f608-4a77-8cc8-6fe96ae1e43f
```

이는 해당 식별자를 가진 Company가 Twenty에 없다는 의미입니다.

<Note>다른 오류와 달리, 이 오류는 데이터 검토 단계에서 감지되지 않습니다. 가져오기가 시작된 뒤 누락된 관계를 만나면 실패합니다.</Note>

### 의미

Twenty에 존재하지 않는 레코드에 연결하려고 하고 있습니다.

### 해결 방법

**옵션 1: 상위 레코드를 먼저 가져오기**

1. 현재 가져오기를 취소
2. 상위 레코드(예: Companies)를 가져오기
3. 그런 다음 하위 레코드(예: People)를 가져오기

**옵션 2: 참조 값 수정**

1. 파일의 참조 값을 확인
2. 기존 레코드와 정확히 일치하는지 확인
3. 형식 확인: 도메인은 `https://domain.com`이어야 합니다

**옵션 3: 관계 제거**

1. 관계 없이 가져오려면 셀을 비우세요
2. 관계를 나중에 수동으로 추가하세요

### 이 오류를 방지하는 방법

1. **올바른 순서로 가져오기:**
   * 회사 먼저
   * 연락처 두 번째(회사 참조 포함)
   * 기회 세 번째

2. **참조 값을 확인하세요:**
   * 정확한 식별자를 얻기 위해 상위 레코드를 내보내세요
   * 도메인은 `https://domain.com` 형식을 사용하세요
   * 오타 및 대소문자 구분 여부를 확인하세요

<Warning>
  **존재하지 않는 레코드를 참조하면 가져오기는 실패합니다.**

  항상 상위 객체를 먼저 가져오세요.
</Warning>

자세한 내용: [관계 가져오기](/l/ko/user-guide/data-migration/capabilities/import-relations)

***

## 오류: 파일이 너무 큼

### 볼 수 있는 내용

이 오류는 **파일을 업로드할 때** 나타나며 — 업로드가 완전히 차단됩니다:

```
레코드가 너무 많습니다. 최대 10,000개까지 허용됩니다
```

파일 크기를 줄이기 전에는 데이터 검토 단계로 진행할 수 없습니다.

### 의미

파일의 레코드가 10,000개를 초과합니다.

### 해결 방법

**옵션 1: 여러 파일로 분할**

1. 데이터를 10,000개 이하의 레코드로 구성된 파일로 나누세요
2. 각 파일을 개별적으로 가져오세요
3. 가져오기 순서를 유지(회사를 연락처보다 먼저)

**옵션 2: API 가져오기 사용**
매우 큰 데이터셋의 경우 레코드 제한이 없는 API를 사용하세요.
참고: [API로 데이터 가져오는 방법](/l/ko/user-guide/data-migration/how-tos/import-data-via-api)

***

## 오류: 필드를 인식할 수 없음

### 의미

필드가 Twenty에 존재하지 않기 때문에 파일의 열을 매핑할 수 없습니다.

### 해결 방법

1. **설정 → 데이터 모델**로 이동
2. 가져올 객체를 선택하세요
3. **+ 필드 추가**를 클릭하세요
4. 적절한 유형으로 커스텀 필드를 생성하세요
5. 파일을 다시 업로드하세요

<Note>CSV 가져오기는 필드가 아니라 레코드를 생성합니다. 가져오기 전에 모든 필드가 존재해야 합니다.</Note>

***

## 오류: 사용자 관계 비어 있음

### 의미

레코드를 사용자(소유자, 담당자)에게 할당하려고 하지만 관계가 매핑되지 않았습니다.

### 일반적인 원인

1. **사용자가 초대를 수락하지 않음** — 해당 사용자는 아직 Twenty에 존재하지 않음
2. **이전 시스템의 사용자 ID 사용** — Twenty는 다른 시스템의 ID를 매칭할 수 없음
3. **잘못된 이메일 형식** — 이메일이 사용자의 Twenty 계정과 일치하지 않음

### 해결 방법

1. 모든 사용자가 Twenty 워크스페이스 초대를 수락했는지 확인하세요
2. 사용자의 이름이나 이전 시스템 ID가 아닌 **이메일 주소**를 사용하세요
3. Twenty에 가입할 때 사용한 것과 동일한 이메일을 사용하세요

<Warning>
  **가져오기를 진행하기 전에 사용자가 초대를 수락해야 합니다.**

  사용자가 초대를 수락하지 않은 경우, 해당 사용자를 참조하는 레코드의 사용자 관계가 비어 있게 됩니다.
</Warning>

***

## 가져오기 전 체크리스트

가져오기 전에 다음을 확인하여 오류를 방지하세요:

### 파일 요구 사항

<Check>파일 형식이 CSV, XLSX 또는 XLS임</Check>
<Check>파일의 레코드가 10,000개 미만임</Check>
<Check>파일이 UTF-8 인코딩을 사용함</Check>

### 데이터 품질

<Check>중복 이메일 없음(연락처용)</Check>
<Check>중복 도메인 없음(회사용)</Check>
<Check>모든 날짜가 일관된 형식을 사용</Check>
<Check>모든 도메인이 `https://domain.com` 형식을 사용</Check>

### 필드 형식

<Check>불리언 필드는 `TRUE` 또는 `FALSE`(대문자) 사용</Check>
<Check>선택 필드는 표시 라벨이 아닌 API 이름 사용</Check>
<Check>전화 필드는 필요한 모든 열 포함</Check>
<Check>통화 필드는 Amount와 Currency Code 모두 포함</Check>

### 관계

<Check>상위 레코드를 하위 레코드보다 먼저 가져오기</Check>
<Check>관계 열이 기존 레코드를 참조</Check>
<Check>도메인 형식이 Twenty의 형식과 정확히 일치</Check>

### 데이터 모델

<Check>모든 커스텀 필드가 설정 → 데이터 모델에 존재</Check>
<Check>가져오기 전에 선택 옵션이 존재</Check>

***

## 아직도 문제가 있나요?

위의 해결책을 시도했다면:

1. **샘플 파일을 다운로드** — Twenty가 기대하는 정확한 형식을 확인하세요
2. **기존 레코드를 내보내기** — 파일을 정상 데이터와 비교하세요
3. **소량으로 테스트** — 먼저 5–10개의 행으로 시도하세요
4. **참고 문서를 확인하세요:**
   * [필드 매핑](/l/ko/user-guide/data-migration/capabilities/field-mapping)
   * [고유성 제약 조건](/l/ko/user-guide/data-migration/capabilities/uniqueness-constraints)
   * [관계 가져오기](/l/ko/user-guide/data-migration/capabilities/import-relations)
   * [오류 처리](/l/ko/user-guide/data-migration/capabilities/error-handling)