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

# 알려진 문제

> XBOX CLI 최신 릴리스의 문제와 완료되지 않은 기능 및 해결 방법입니다.

이 페이지에는 완료되지 않은 기능을 포함하여 XBOX CLI 최신 릴리스의 알려진 문제가
나와 있습니다. 문제가 여기에 나와 있으면 보고할 필요가 없습니다.

최신 릴리스만 지원됩니다. [`xbox upgrade`](https://docs.xbox.com/ko/tools/xbox-cli/commands/upgrade)는 최신 릴리스를 사용할 수 있는지
알려 줍니다. **수정됨**으로 표시된 항목은 최신 릴리스에서 수정되었으며, 다음 릴리스에서
제거됩니다.

## 문제가 나와 있지 않은 경우

1. [`xbox upgrade`](https://docs.xbox.com/ko/tools/xbox-cli/commands/upgrade)로 최신 릴리스를 실행하고 있는지 확인합니다.
2. [기존 문제](https://github.com/xbox/cli/issues)를 검색합니다.
3. 보고되지 않은 문제라면 [`xbox feedback`](https://docs.xbox.com/ko/tools/xbox-cli/commands/feedback)으로 보고합니다. 이 명령은
   환경 세부 정보가 채워진 버그 보고서를 엽니다. 문제는 공개되므로 공개적으로 공유하지 않을
   내용은 제외하세요.

## CLI 업데이트

### `xbox upgrade`가 HTTP 301로 실패함

**수정됨**

CLI의 공개 리포지토리가 이동되어 v0.2.1의 [`xbox upgrade`](https://docs.xbox.com/ko/tools/xbox-cli/commands/upgrade)가 매번
`HTTP 301: GitHub release metadata is unavailable`로 실패합니다.

**해결 방법:** [설치](https://docs.xbox.com/ko/tools/xbox-cli/installation.md)에 따라 최신 릴리스를 다운로드합니다.

## 로그인 및 권한

### 일부 명령이 아직 개인 Microsoft 계정에서 작동하지 않음

회사 또는 학교 계정이 아닌 개인 Microsoft 계정으로 로그인하면 XBOX services 구성, 테스트 계정,
패키지, 플레이테스트 및 대상 그룹에 대한 명령이 작동하지 않습니다. XBOX services 구성 및
테스트 계정 명령은 서비스를 사용할 수 없다고 보고되는 HTTP 502로 실패하지만, 다시 시도해도 해결되지 않습니다.

**해결 방법:** 회사 또는 학교 계정으로 Partner Center에서 판매자에 참가하고, 해당 계정으로
CLI에 로그인합니다.

### `xbox game`, `xbox xbl` 및 유사한 명령이 아직 서비스 주체를 허용하지 않음

서비스 주체는 로그인할 수 있지만, 서비스 주체가 `audience`, `game`, `package`, `playtest`, `sandbox`,
`seller`, `test-account` 및 `xbl` 명령을 실행하면 권한 부여 오류로 실패합니다.
이러한 명령이 호출하는 서비스가 아직 서비스 주체를 허용하지 않기 때문입니다.

**해결 방법:** 로그인한 사용자로 해당 명령을 실행합니다. `xbox playfab` 명령은 사람이
[`xbox playfab service-principal set`](https://docs.xbox.com/ko/tools/xbox-cli/commands/playfab/service-principal)으로 액세스 권한을 부여하면
서비스 주체로 작동합니다.
[자동화(서비스 주체) 인증](https://docs.xbox.com/ko/tools/xbox-cli/authentication.md#automation-service-principal-authentication)을 참조하세요.

### 둘 이상의 판매자에 속한 경우 일부 판매자에 대한 명령이 거부됨

둘 이상의 Partner Center 판매자에 속한 경우 XBOX services 구성, 테스트 계정,
패키지, 플레이테스트 및 대상 그룹에 대한 명령이 Partner Center에서 마지막으로 선택한 판매자를
제외한 모든 판매자에 대해 거부될 수 있습니다.

**해결 방법:** Partner Center에서 원하는 판매자를 선택한 다음, 명령을 다시 실행합니다.

### `xbox seller list`에서 판매자 중 하나가 누락되는 경우가 있음

둘 이상의 Partner Center 판매자에 속한 경우 [`xbox seller list`](https://docs.xbox.com/ko/tools/xbox-cli/commands/seller)가
오류 없이 판매자 중 하나를 누락하는 경우가 있으며, 다음 실행에서는 해당 판매자가 나열될 수 있습니다. 판매자가
누락된 동안에는 [`xbox audience list`](https://docs.xbox.com/ko/tools/xbox-cli/commands/audience)와 같은 해당 판매자에 대한 명령이
거부될 수 있으며, Partner Center에서 해당 판매자를 선택해도 해결되는지는 알려져 있지 않습니다.

### `xbox game` 명령이 `--seller-id`를 무시함

[`xbox game list`, `xbox game get` 및 `xbox game create`](https://docs.xbox.com/ko/tools/xbox-cli/commands/game)는 `--seller-id`로 전달하거나
[컨텍스트](https://docs.xbox.com/ko/tools/xbox-cli/commands/context.md)에 저장한 판매자가 아니라 Partner Center에서 마지막으로 선택한
판매자를 사용하므로, `game create`가 다른 판매자에 게임을 만들 수 있습니다. 잘못 입력한 ID처럼
본인의 것이 아닌 판매자 ID를 사용해도 명령이 실패하지 않으며, 본인의 게임을
반환합니다.

**해결 방법:** Partner Center에서 원하는 판매자를 선택한 다음, 게임을 만들기 전에 `xbox game list`에
해당 판매자의 게임이 표시되는지 확인합니다. 변경 사항이 CLI에 반영되기까지 최대 15분이 걸릴 수 있습니다.

### `xbox sandbox` 명령이 전역 샌드박스만 표시함

`--seller-id`로 전달하거나 [컨텍스트](https://docs.xbox.com/ko/tools/xbox-cli/commands/context.md)에 저장한 판매자가 Partner Center에서
마지막으로 선택한 판매자가 아닌 경우,
[`xbox sandbox list` 및 `xbox sandbox get`](https://docs.xbox.com/ko/tools/xbox-cli/commands/sandbox)은 실패하지 않고 `CERT`,
`CERT.DEBUG` 및 `RETAIL` 샌드박스만 찾습니다. `xbox sandbox create`는 마지막으로 선택한 판매자에
샌드박스를 만들며, 해당 판매자가 다른 판매자인 경우 샌드박스를 다시 읽을 수 없어 `4`로
종료됩니다. 샌드박스를 다시 만들지 마세요.

**해결 방법:** Partner Center에서 원하는 판매자를 선택한 다음, 해당 판매자로 명령을 다시
실행합니다. 변경 사항이 CLI에 반영되기까지 최대 15분이 걸릴 수 있습니다.

## 플레이테스트 및 대상 그룹으로 테스트

### `xbox audience list`가 시간 초과될 수 있음

[`xbox audience list`](https://docs.xbox.com/ko/tools/xbox-cli/commands/audience)는 요청이 시간 초과될 만큼 오래 걸릴 수
있습니다. `--name`은 모든 대상 그룹을 읽은 후에 목록을 필터링하므로 도움이 되지 않습니다.

## XBOX services 구성

### 다운로드한 일부 XML 문서가 잘못된 인코딩을 선언함

[`xbox xbl config download --view published`](https://docs.xbox.com/ko/tools/xbox-cli/commands/xbl)가 저장하는
`mpsdtitleinfo.xml` 및 `titlename-localization.xml`과 같은 일부 게시된 XML 문서는 `encoding="utf-16"`을
선언하지만 UTF-8로 인코딩되어 있으므로, 선언을 신뢰하는 XML 판독기는 이를 로드하지 못합니다.

**해결 방법:** 구문 분석하기 전에 파일을 UTF-8로 디코딩합니다.

## PlayFab

### `xbox playfab api /Admin/UpdatePolicy`가 확인 없이 정책을 덮어쓸 수 있음

요청 본문에 `"OverwritePolicy": true`가 있으면 이 호출은 `xbox playfab api-policy set --overwrite`의
보호 장치 없이 타이틀의 전체 API 액세스 정책을 바꿉니다. `--confirm`이
필요하지 않으며, 저장된 컨텍스트 또는 `XBOX_PLAYFAB_TITLE_ID`의 타이틀을 사용할 수 있습니다.
잘못된 정책은 모든 플레이어가 타이틀에 액세스하지 못하게 할 수 있습니다.

**해결 방법:** 대신 [`xbox playfab api-policy set --overwrite`](https://docs.xbox.com/ko/tools/xbox-cli/commands/playfab/api-policy)를
사용하세요. 이 명령에는 `--confirm`과 `--playfab-title-id`로 전달된 타이틀이 필요합니다.

### `playfab title-data delete` 및 `playfab player-data delete`가 먼저 확인을 요청하지 않음

무언가를 삭제하는 다른 명령은 실행하기 전에 확인을 요청하거나 `--confirm` 없이는 거부합니다. 이
두 명령은 지정한 키를 즉시 삭제합니다.

### `--keys` 및 `--member-ids`가 쉼표로 구분된 목록을 받음

`xbox playfab title-data` 및 `xbox playfab player-data`의 `--keys`와
[`xbox playfab group member`](https://docs.xbox.com/ko/tools/xbox-cli/commands/playfab/group)의 `--member-ids`는 쉼표로 구분된 목록을 받습니다. 이러한 옵션은
반복 옵션으로 변경될 예정이므로 이를 사용하는 스크립트는 업데이트해야 합니다.

그때까지 `--keys`는 쉼표가 포함된 키를 지정할 수 없습니다. 이러한 키를 읽으려면 이름 전체를 받는
`--key`로 전달하세요. 하지만 `delete`에는 `--keys`만 있습니다.

**해결 방법:** 키를 삭제하려면 [`xbox playfab api`](https://docs.xbox.com/ko/tools/xbox-cli/commands/playfab/api)로
`delete`가 사용하는 API를 호출합니다. 타이틀 데이터의 경우 키 값을 `null`로 설정하며,
내부 타이틀 데이터의 경우 대신 `/Admin/SetTitleInternalData`를 사용합니다.

```bash theme={null}
xbox --playfab-title-id ABC123 playfab api /Admin/SetTitleData --body '{"Key":"Level,Bonus","Value":null}'
```

플레이어 데이터의 경우 [플레이어 데이터](https://docs.xbox.com/ko/tools/xbox-cli/commands/playfab/player-data.md)에서 데이터의 표시 유형에 맞는
업데이트 API를 사용하여 `KeysToRemove`에 키를 나열합니다.

```bash theme={null}
xbox --playfab-title-id ABC123 playfab api /Admin/UpdateUserData --body '{"PlayFabId":"PLAYER123","KeysToRemove":["Level,Bonus"]}'
```

## 스크립트 및 에이전트

### 대부분의 명령은 변경 적용 여부를 알 수 없을 때 1로 종료함

일부 명령은 요청을 보낸 후 시간 초과되는 경우처럼 변경이 적용되었는지 알 수 없을 때
`3`으로 종료하며, 해당 페이지에 그렇게 명시되어 있습니다. 모든 PlayFab 명령을 포함한
다른 모든 명령은 모든 실패에 대해 `1`로 종료하므로, 스크립트는 이 경우와 변경이 적용되지 않은 경우를
구분할 수 없습니다.

**해결 방법:** 무언가를 변경하는 명령이 실패하면 다시 실행하기 전에 현재 상태를
확인하세요.


## Related topics

- [PC 개발을 위한 Unity 시작하기(콘텐츠)](https://docs.xbox.com/ko/build/gdk-and-engines/unity/unity.md)
- [릴리스 노트 - XBOX PC Remote Tools(2026년 3월)](https://docs.xbox.com/ko/tools/tools-pc/xbox-pc-remote-tools/release-notes/2603.md)
- [Playtest 사용](https://docs.xbox.com/ko/publishing/game-publishing/concepts/playtest-preview.md)
- [XBOX PC Remote Tools FAQ 및 문제 해결 가이드](https://docs.xbox.com/ko/tools/tools-pc/xbox-pc-remote-tools/faq.md)
- [Visual Studio 2019 GDK 지원 정보](https://docs.xbox.com/ko/tools/tools-console/visualstudio/vs-2019-support-notes.md)
