> For the complete documentation index, see [llms.txt](https://docs.decentraland.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.decentraland.org/creator/content-creator-ko/sdk7/debugging/troubleshooting.md).

# 문제 해결

일반적인 문제에 대한 수정 방법

## AI 어시스턴트로 디버깅하기

아래의 문제들을 살펴보기 전에, 문제를 Cursor의 채팅, GitHub Copilot, Claude Code 같은 AI 어시스턴트에게 맡겨 보세요. 콘솔의 오류 메시지를 붙여 넣거나, 예상대로 동작하지 않는 부분을 설명하면, 보통은 씬 코드에서 문제를 찾아 고쳐 줄 수 있습니다.

좋은 결과를 얻으려면 AI에 Decentraland SDK 스킬이 설치되어 있는지 확인하세요. 이 스킬은 SDK의 패턴과 제약을 알려 주므로, 일반적이거나 오래된 정보에 근거해 추측하지 않게 해 줍니다. 씬 프로젝트에서 다음 명령을 실행해 설치하세요:

```bash
npx skills add decentraland/sdk-skills
```

참고 [AI와 함께하는 바이브 코딩](/creator/content-creator-ko/sdk7/getting-started/vibe-coding.md) AI 어시스턴트를 설정하고 프롬프트를 주는 방법에 대한 자세한 내용은

실행 중인 *동안 씬을 AI가 디버깅하도록 할 수도 있습니다*. Decentraland 데스크톱 클라이언트는 MCP 서버를 노출할 수 있어서, 에이전트가 직접 스크린샷을 찍고, 씬의 콘솔 출력을 읽고, 플레이어를 이동시키고, 오브젝트를 클릭할 수 있습니다. 즉, 여러분이 버그를 재현하고 오류를 붙여 넣는 대신 에이전트가 스스로 재현하고, 무슨 일이 일어나는지 확인한 다음, 수정될 때까지 반복합니다. 씬을 `npm run start -- --mcp` 로 실행하고 에이전트를 연결하세요.

참고 [AI가 인월드에서 당신의 씬을 보게 하기](/creator/content-creator-ko/sdk7/getting-started/vibe-coding.md#let-the-ai-see-your-scene-in-world) 전체 설정 방법은 `unity-explorer-mcp` 스킬을 설치해 에이전트가 작업 흐름을 이해하도록 하세요:

```bash
npx skills add decentraland/sdk-skills --skill unity-explorer-mcp
```

## 미리보기 실행 시 발생하는 문제

#### 문제: 어떤 씬 미리보기도 실행할 수 없고, 오류 메시지에 **권한이 거부되었습니다** 또는 **EACCES**

운영 체제에서 프로젝트를 실행하려는 폴더의 권한을 수정하도록 허용하지 않습니다. 씬을 실행할 때 일부 종속성을 설치해야 하지만, 그 작업이 금지되어 있습니다. Windows/Mac/Linux 사용자 계정이 해당 폴더의 파일을 수정할 수 있도록 폴더 권한을 설정해야 합니다.

유용한 자료:

* [docs.npmjs](https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally)
* [letscodepare](https://letscodepare.com/blog/npm-resolving-eacces-permissions-denied)

#### 문제: 특정 씬 미리보기를 실행할 수 없고, 오류에 **오류: 프로젝트 빌드 중 오류 발생**

공유받은 씬을 실행하는 경우, 해당 씬이 `node_modules` 또는 `bin` 폴더나 `package-lock.json` 파일을 포함한 상태로 공유되지 않았는지 확인하세요. 이 파일들은 OS와 기기에 특화된 버전의 종속성을 담고 있으며, 씬을 처음 실행할 때 생성되어야 합니다. 이 폴더와 파일을 수동으로 삭제한 뒤 `npm run start` 를 다시 실행하세요.

#### 문제: `npm run start` 를 실행하면 실행은 되지만 오류 메시지는 없고, 브라우저 창도 열리지 않으며, 미리보기를 열 URL도 출력에 없습니다

Node 버전이 최신인지 확인하세요. 20 이상이어야 합니다.

#### 문제: `npm run start` 브라우저 탭은 열리지만 로딩 화면이 끝까지 로드되지 않거나, "critical error"라고 표시된 빨간 오류 배너가 보입니다.

* 프로젝트에 최신 버전의 Decentraland SDK가 설치되어 있는지 확인하세요. 다음을 실행하세요:

  `npm i @dcl/sdk@latest`

#### 문제: 씬은 실행되지만, 콘솔에서 `순환 종속성` 경고가 보입니다.

이는 씬의 파일들이 서로를 상호 참조하고 있음을 의미합니다. 이것이 반드시 문제는 아니지만, 디버깅하기 어려운 경쟁 상태와 기타 문제를 초래할 수 있어 소프트웨어 작성 방식으로는 권장되지 않는 패턴입니다. 이러한 경고가 있어도 씬은 대체로 잘 동작할 가능성이 높습니다.

이상적으로는, 씬의 코드 로딩이 명확한 순차적 순서를 따라야 합니다. 순환 종속성이 있는 코드는 컴파일러가 무엇을 먼저 시작해야 할지 알지 못하는 치킨 앤 에그 문제를 겪을 수 있습니다. 자주 문제 없이 해결되지만, 피하는 것이 좋은 습관입니다.

이러한 종속성을 수정하려면, 보통은 이미 인스턴스화된 엔티티/오브젝트에 대한 참조를 함수 인자로 전달하면서 함수나 오브젝트 생성자를 호출해야 합니다. 함수 안에 아직 인스턴스화되었을 수도 있고 아닐 수도 있는 이러한 엔티티/오브젝트에 대한 참조를 하드코딩하는 대신 말입니다.

## 배포 시 발생하는 문제

#### 문제: 이 패럿에 배포할 권한이 없습니다

* 다음이 `scene.json` 에 배포하려는 좌표를 올바르게 나열하고 있는지 확인하세요.
* Metamask가 올바른 지갑으로 트랜잭션 서명을 하도록 제대로 설정되어 있는지 확인하세요. 이는 LAND 토큰을 소유한 지갑일 수도 있고, 소유자로부터 운영자 권한을 부여받은 지갑일 수도 있습니다.

#### 문제: `npm run deploy` 실패합니다

* 씬의 스폰 지점을 확인하세요. 스폰 지점의 x,y,z 좌표 세 개는 각각 숫자이거나 범위여야 합니다. 세 좌표가 모두 숫자이거나 모두 범위여야 합니다. 일부는 범위이고 일부는 숫자인 것은 지원되지 않습니다.

  예를 들어, 다음은 지원되지 않습니다:

  `"position": {"x": [1,4], "y": 0, "z": [1,4]}`

  다음은 지원됩니다:

  `"position": {"x": [1,4], "y": [0,0], "z": [1,4]}`
* 배포 대상으로 할당된 기본 catalyst 서버가 중단되었거나 문제가 있을 수 있습니다. 대신 `npm run deploy` 명령을 사용해 특정 catalyst 서버에 배포하도록 강제할 수 있습니다. Decentraland Editor에서 특정 서버에 배포하려면:

  1. 씬을 열고 **게시**
  2. 옵션을 선택하세요 **다른 서버에 게시** 아래쪽에서.
  3. 드롭다운에서 **사용자 지정 서버**
  4. 서버 주소를 입력하세요. 예: `peer-ec1.decentraland.org`
  5. 클릭 **사용자 지정 서버에 게시**
  6. 일반 배포와 마찬가지로 트랜잭션을 승인하세요.

  CLI로 하려면:

  `npm run deploy -- --target-content <server-name>`

  예를 들면:

  `npm run deploy -- --target-content peer-ec1.decentraland.org`

  참고 [catalyst-monitor](https://decentraland.github.io/catalyst-monitor/) 를 사용해 catalyst 네트워크의 모든 서버 상태를 확인하세요. 각 카드 상단에서 각 서버의 주소도 복사할 수 있습니다.
* 씬의 `package.json`. 흔한 문제는 `bundleDependencies` 와 함께 `bundledDependencies` (d가 하나 더 붙은) 섹션이 있는 경우입니다. 이는 같은 프로젝트에서 서로 다른 시점에 다른 Node 버전을 실행했거나, 서로 다른 Node 버전이 설치된 사람들 사이에서 프로젝트를 공유한 결과일 수 있습니다. `bundleDependencies`을 삭제하세요. 이는 더 오래된 Node 버전과 관련된 항목입니다.

또한 Node 버전이 최신인지, 최소 20 버전인지 확인하세요.

#### 문제: `npm run deploy` 또는 `npm run build` 타입 오류를 보고합니다

씬에 TypeScript가 보고하는 타입 오류가 있을 수 있습니다. 예를 들어 특정 변수가 다음 타입일 수 있다고 표시하거나 `아무` 이거나 `undefined` 또는 `null` 허용되지 않는다고 말할 수 있습니다. `npm run deploy`를 실행하면 `npm run build`도 함께 실행되며, 이는 `npm run start`.

자바스크립트와 달리 TypeScript는 모든 변수에 대해 엄격한 টাই핑을 강제합니다. 씬이 예를 들어 특정 값이 절대 `undefined`이 되지 않도록 작성되어 있더라도, TypeScript는 그런 상황에서 무엇이 일어나는지 알아야 하거나, 그 값이 예를 들어 문자열만 될 수 있다고 명시적으로 밝혀야 합니다.

대안으로, `npm run deploy -- --skip-build` 를 실행해 `npm run build`의 실행을 건너뛰고 이러한 검사가 실행되지 않게 할 수 있습니다.

#### 문제: 씬을 배포했는데 Decentraland에 들어가도 변경 사항이 보이지 않습니다

* 씬에 무거운 자산이 포함되어 있으면 몇 분이 걸릴 수 있다는 점을 기억하세요.
* 새 버전의 3D 모델이 자산 번들로 변환되는 동안, 플레이어에게는 의도적으로 씬의 마지막으로 정상 동작한 버전이 제공됩니다. 보통은 몇 초만 걸리지만, 매우 큰 씬이거나 서버가 바쁠 때는 더 오래 걸릴 수 있습니다. 직접 [변환 상태를 확인할 수 있습니다](/creator/content-creator-ko/scene-editor/publish/publish-scene.md#check-the-conversion-status) .
* 새 버전을 가져오려면 씬을 다시 로드하는 것만으로는 충분하지 않습니다. 다시 로드하면 씬의 코드는 재시작되지만, 새로 게시된 버전은 가져오지 않습니다. 변환이 완료되면 Decentraland를 완전히 종료했다가 다시 실행한 다음, 점프 링크나 `/goto` 채팅 명령으로 씬에 다시 들어가세요.

#### 문제: 어떤 플레이어는 내 씬의 새 버전을 보고, 다른 플레이어는 여전히 이전 버전을 봅니다

씬의 3D 모델 변환은 플랫폼(Windows와 Mac)마다 완료 시점이 다르고, 각 플레이어의 클라이언트도 로컬 캐시를 유지합니다. 모든 플랫폼에서 변환이 완료되었는지 확인하려면 [변환 상태를 확인할 수 있습니다](/creator/content-creator-ko/scene-editor/publish/publish-scene.md#check-the-conversion-status) 하고 `윈도우` 및 `맥` 값을 `assetBundles`아래에서 비교하세요. 둘 다 `완료됨`이 되면, 영향을 받는 플레이어들에게 Decentraland를 완전히 종료했다가 다시 실행하라고 요청하세요.

#### 문제: 게시가 변환 단계에서 멈춰 있고, Jump In 버튼이 절대 나타나지 않습니다

씬이 다른 변환 중인 씬들 뒤에서 대기열에 있거나, 변환에 실패한 것입니다.

* Open `https://asset-bundle-registry.decentraland.org/queues/status` 하고 씬의 엔티티 ID를 찾으세요. 해당 ID는 `entityId` 필드에서 찾을 수 있습니다 [변환 상태를 확인할 수 있습니다](/creator/content-creator-ko/scene-editor/publish/publish-scene.md#check-the-conversion-status) 씬의 좌표를 사용해
* 대기열에 있다면 씬이 대기 중인 것이므로 그냥 기다리면 됩니다. [변환 상태를 확인할 수 있습니다](/creator/content-creator-ko/scene-editor/publish/publish-scene.md#check-the-conversion-status) 에 없다면 `실패함`이 씬의 경우입니다. 플랫폼이 [문제를 보고하고](/creator/content-creator-ko/sdk7/debugging/report-bug.md) 엔티티 ID를 포함하세요.

#### 문제: 배포한 뒤 일부 3D 모델이 누락되었거나, 검게 보이거나, 텍스처가 없습니다

* 방금 게시했다면 모델을 자산 번들로 변환하는 작업이 아직 완료되지 않았을 수 있습니다. 채팅 창에 `/detectabs` 를 입력하세요. 빨간색으로 표시된 모델은 아직 변환되지 않은 것입니다. [변환 상태 확인](/creator/content-creator-ko/scene-editor/publish/publish-scene.md#check-the-conversion-status) 을 입력하고 완료될 때까지 기다리세요.
* 3D 모델과 그 바운딩 박스까지 모두 씬 경계 안에 있는지 확인하세요. 미리보기 실행 시 모델의 일부가 이 한계를 벗어나면, 튀어나온 부분은 잘려서 렌더링되지 않으며, 미리보기와 게시된 씬 모두에서 그렇게 됩니다.
* 텍스처가 문제라면, 3D 모델의 텍스처는 변환 중 최대 1024x1024픽셀로 제한된다는 점을 기억하세요.

#### 문제: 가까이서는 씬이 괜찮아 보이지만, 멀리서 보면 깨지거나 누락됩니다

멀리서 씬을 렌더링하는 데 사용되는 자산의 낮은 디테일 수준(LOD) 버전은 게시의 마지막 단계에서 생성되며 아직 완료되지 않았을 수 있습니다. 이 때문에 가까이서 씬을 테스트하는 것은 막히지 않습니다. [변환 상태 확인](/creator/content-creator-ko/scene-editor/publish/publish-scene.md#check-the-conversion-status) 하고 `lods`아래의 값을 살펴보거나, 잠시 기다렸다가 나중에 다시 확인하세요.

#### 문제: 배포 후 3D 모델이 다르게 보입니다

* 텍스처가 다르게 보인다면, 3D 모델의 텍스처는 최대 1024x1024픽셀로 제한된다는 점을 기억하세요. 이 변환은 Decentraland가 모두에게 원활하게 동작하도록 하기 위해 수행됩니다.
* 모델이 다르게 보인다면 모델의 자산 번들 변환에 문제가 있을 수 있습니다. 자산 번들 압축에 대해 자세히 읽어보세요 [여기](/creator/content-creator-ko/sdk7/optimizing/performance-optimization.md#asset-bundle-conversion).

  이를 검증하려면 URL 매개변수 `&DISABLE_ASSET_BUNDLES`를 사용해 씬을 실행해 보세요. 이 플래그를 사용했을 때 모델이 정상이라면, 문제는 모델 변환 버그와 관련되어 있어야 합니다. 그런 경우에는 [문제를 보고하고](/creator/content-creator-ko/sdk7/debugging/report-bug.md) 하고 배포의 엔티티 ID를 포함하세요.

  모델의 압축된 자산 번들 버전을 생성하는 데 서버가 약간의 시간이 걸린다는 점을 기억하세요(보통 몇 분, 매우 큰 씬이거나 서버가 바쁠 때는 더 오래 걸림). 채팅 창에 다음 명령을 입력하면 모델이 압축된 자산 번들로 로드되는지 아닌지 확인할 수 있습니다 `/detectabs`. 압축된 모델은 초록색으로, 압축되지 않은 모델은 빨간색으로 표시됩니다.

  게시하기 전에 미리보기에서 [최적화된 자산을 활성화하여](/creator/content-creator-ko/sdk7/getting-started/preview-scene.md#preview-with-optimized-assets)이 변환을 로컬에서도 재현할 수 있습니다. 그러면 씬을 배포하지 않고도 이런 문제를 잡아내고 디버깅할 수 있습니다.

#### 문제: 내 씬이 완전히 사라졌습니다

* 씬이 월드에 있는 경우: NAME, LAND 또는 MANA를 판매하거나 이전한 뒤 월드 저장소 예산을 초과했을 수 있습니다. 월드에 접근할 수 없게 되기 전에 48시간 내에 공간을 확보하거나 예산을 늘려야 합니다. Creator Hub의 **관리** 탭 또는 **Worlds** 탭에서 확인할 수 있습니다. [Builder](https://decentraland.org/builder/worlds)에서 예산을 확인한 뒤 다시 게시하세요. 다음을 참조하세요 [World 크기 제한](/creator/content-creator-ko/sdk7/kinds-of-projects/kinds-of-project.md#size-limits).
* 씬이 LAND에 있는 경우: 배포 권한이 있는 누군가가 당신의 패럿 위에 새 씬을 게시했을 수 있으며, 그러면 이전 콘텐츠가 지워집니다. 다음을 참조하세요 [씬 덮어쓰기](/creator/content-creator-ko/sdk7/publishing/publishing.md#scene-overwriting).
* 드문 경우지만, Decentraland의 콘텐츠 정책을 위반하는 콘텐츠는 콘텐츠 서버에서 차단 목록에 올라갈 수 있습니다. 이것이 실수라고 생각된다면, 다음을 통해 문의하세요 [Decentraland Discord](https://decentraland.org/discord).

#### 문제: 미리보기에서는 부드럽게 실행되는데, 운영 환경에서는 FPS가 낮습니다.

나쁜 관행을 따르는 인접 씬들 때문에 씬 성능이 영향을 받을 수 있습니다. 이들 역시 병렬로 실행되기 때문입니다. 설정을 열고 시야 거리를 최소로 설정하면, 현재 씬 주변의 패럿 1개만 로드되므로 이것이 원인인지 확인할 수 있습니다.

매개변수 `&LOS=0`를 사용해 씬을 실행하면 시야 거리를 더 줄여 주변 씬을 아예 로드하지 않게 할 수 있습니다.

방금 씬을 배포했다면, 서버가 씬의 3D 모델을 압축된 자산 번들로 변환한 뒤 씬을 로드할 때의 부담도 줄어들 수 있습니다. 채팅 창에 다음 명령을 입력하면 모델이 압축된 자산 번들로 로드되는지 아닌지 확인할 수 있습니다 `/detectabs`. 압축된 모델은 초록색으로, 압축되지 않은 모델은 빨간색으로 표시됩니다.

### 버그 신고

문제가 여러분의 장면이 아닌 Decentraland SDK 일반 문제라면, 다음을 참고하세요 [버그 신고](/creator/content-creator-ko/sdk7/debugging/report-bug.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.decentraland.org/creator/content-creator-ko/sdk7/debugging/troubleshooting.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.