> 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`

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

이는 씬의 파일들이 서로를 상호 참조한다는 뜻입니다. 이것이 반드시 문제는 아니지만, 디버그하기 어려운 레이스 컨디션과 다른 문제를 일으킬 수 있어 소프트웨어 작성 방식으로는 권장되지 않습니다. 이러한 경고가 있어도 씬은 아마 잘 동작할 것입니다.

이상적으로는, 씬의 코드 로딩이 명확한 순차적 순서를 따라야 합니다. 순환 종속성이 있는 코드는 닭이 먼저냐 달걀이 먼저냐 같은 문제가 생길 수 있는데, 컴파일러가 무엇을 먼저 시작해야 하는지 알지 못하기 때문입니다. 종종 문제 없이 해결되지만, 피하는 것이 좋은 습관입니다.

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

## 배포할 때 발생하는 문제

#### 문제: 이 parcel들에 배포할 권한이 없습니다

* 다음을 확인하세요: `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` (extra 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`.

JavaScript와 달리 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) 그리고 다음을 비교하세요: `Windows` 과 `Mac` 아래의 값 `assetBundles`. `완료`가 되면, 영향을 받는 플레이어에게 Decentraland를 완전히 종료하고 다시 실행하도록 요청하세요.

#### 문제: 게시가 변환 중 단계에서 멈추고, Jump In 버튼이 끝내 나타나지 않습니다

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

* 열기 `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) 씬의 좌표를 사용하여 검색합니다. ID가 대기열에 나열되어 있다면, 씬은 대기열에 있는 것이므로 기다리기만 하면 됩니다.
* 대기열에 없다면, [변환 상태를 확인하세요](/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 픽셀 크기로 제한된다는 점을 기억하세요.

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

씬을 멀리서 렌더링할 때 사용되는, 에셋의 낮은 Level of Detail(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). 이를 통해 씬을 배포하지 않고도 이러한 문제를 찾아 디버그할 수 있습니다.

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

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

#### 문제: 미리 보기에서는 매끄럽게 실행되지만 프로덕션에서는 씬의 FPS가 낮습니다.

옆의 씬들도 병렬로 실행되기 때문에, 나쁜 관행을 따르는 이웃 씬들이 씬 성능에 영향을 줄 수 있습니다. 설정을 열고 시야 거리를 최소로 설정하여 현재 씬 주변의 1 parcel만 로드되도록 하면 이 경우인지 확인할 수 있습니다.

다음 매개변수로 씬을 실행하여 시야 거리를 더 줄일 수 있습니다: `&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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.