> 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-pt/scenes-sdk7/depuracao/troubleshooting.md).

# Solução de Problemas

Correções para problemas comuns

## Depure com um assistente de IA

Antes de vasculhar os problemas abaixo, considere passar o problema para um assistente de IA, como o chat do Cursor, GitHub Copilot ou Claude Code. Cole a mensagem de erro do console, ou descreva o que não está funcionando como esperado, e ele normalmente consegue encontrar o problema no código da sua scene e corrigi-lo para você.

Para obter bons resultados, certifique-se de que a IA tem as skills do Decentraland SDK instaladas. As skills ensinam os padrões e restrições do SDK, para que ela não adivinhe com base em informações genéricas ou desatualizadas. Instale-as executando este comando no projeto da sua scene:

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

Veja [Vibe Coding com IA](/creator/content-creator-pt/scenes-sdk7/primeiros-passos/vibe-coding.md) para mais detalhes sobre a configuração e os prompts para assistentes de IA.

Você também pode deixar a IA depurar a scene *enquanto ela está em execução*. O cliente desktop do Decentraland pode expor um servidor MCP que permite a um agente tirar suas próprias capturas de tela, ler a saída do console da scene, mover o player e clicar em objetos — então, em vez de você reproduzir o bug e colar o erro, o agente o reproduz por conta própria, vê o que acontece e itera até que seja corrigido. Inicie a scene com `npm run start -- --mcp`  e conecte seu agente a ele.

Veja [Deixe a IA ver sua scene no mundo](/creator/content-creator-pt/scenes-sdk7/primeiros-passos/vibe-coding.md#let-the-ai-see-your-scene-in-world)  para a configuração completa, e instale a `unity-explorer-mcp` skill para que o agente conheça o fluxo de trabalho:

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

## Problemas ao executar preview

#### Problema: Não consigo executar nenhuma preview de scene, a mensagem de erro diz que menciona **Permissões negadas** ou **EACCES**

O seu sistema operacional não permite que você edite permissões na pasta onde quer executar o projeto. Ao executar a scene, algumas dependências precisam ser instaladas, mas isso é proibido. Você precisa configurar as permissões da pasta para permitir que sua conta de usuário do Windows/Mac/Linux edite arquivos nela.

Recursos úteis:

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

#### Problema: Não consigo executar a preview de uma scene específica, o erro diz **Erro: erro ao compilar o projeto**

Se você estiver executando uma scene que foi compartilhada com você, certifique-se de que essa scene não tenha sido compartilhada contendo uma `node_modules` ou `bin` pasta, ou um `package-lock.json` arquivo. Esses arquivos contêm dependências que usam versões específicas do seu sistema operacional e da sua máquina; eles devem ser gerados quando a scene for executada pela primeira vez. Exclua essas pastas e esse arquivo manualmente e, em seguida, execute `npm run start` novamente.

#### Problema: executando `npm run start` é executado, não há mensagem de erro, mas nenhuma janela do navegador abre e nenhuma URL aparece na saída para abrir a preview

Certifique-se de que a sua versão do Node esteja atualizada. Ela deve ser 20 ou superior.

#### Problema: executando `npm run start` abre uma aba do navegador, mas a tela de carregamento nunca termina de carregar, ou vejo um banner vermelho de erro que diz "critical error".

* Certifique-se de ter a versão mais recente do Decentraland SDK instalada no seu projeto. Execute:

  `npm i @dcl/sdk@latest`

#### Problema: A scene é executada, no console vejo `Dependências cíclicas` avisos.

Eles se referem a arquivos na sua scene que fazem referência mútua uns aos outros. Isso não é necessariamente um problema, mas não é um padrão recomendável para escrever software, pois pode levar a condições de corrida difíceis de depurar e outros problemas. É provável que sua scene funcione bem apesar desses avisos.

Idealmente, o carregamento do código na sua scene deve seguir uma ordem sequencial clara. Código com dependências cíclicas pode sofrer do problema do ovo e da galinha, em que o compilador não sabe qual iniciar primeiro. Muitas vezes isso é resolvido sem problemas, mas é uma boa prática evitar.

Para corrigir essas dependências, muitas vezes você precisará recorrer a chamadas de funções ou construtores de objetos, passando referências a entities/objects já instanciadas nos argumentos da função; em vez de codificar essas referências às entities/objects na função, que podem ou não já estar instanciadas.

## Problemas ao fazer deploy

#### Problema: Você não tem permissão para fazer deploy nestes parcels

* Certifique-se de que o `scene.json` arquivo da sua scene lista corretamente as coordenadas onde você quer fazer deploy.
* Certifique-se de que o MetaMask está configurado corretamente para usar a wallet certa para assinar a transação. Essa pode ser a wallet que possui os tokens LAND, ou pode ter permissões de operador concedidas pelo proprietário.

#### Problema: executando `npm run deploy` falha

* Verifique os spawn points da sua scene; todas as três coordenadas x, y, z de um spawn point devem ser um número ou um intervalo. Ou as três são números, ou as três são intervalos. Não é suportado ter intervalos para algumas e números para outras.

  Por exemplo, isto não é suportado:

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

  Isto é suportado:

  `"position": {"x": [1,4], "y": [0,0], "z": [1,4]}`
* O servidor catalyst padrão para o qual você recebeu a atribuição de fazer deploy pode estar fora do ar ou com problemas. Você pode forçar o `npm run deploy`  comando a fazer deploy para um servidor catalyst específico, em vez disso. Para fazer deploy para um servidor específico no Decentraland Editor:

  1. Abra sua scene e clique em **Publish**
  2. Selecione a opção **Publicar para um server diferente** na parte inferior.
  3. No dropdown, selecione **Custom Server**
  4. Insira o endereço do servidor, por exemplo `peer-ec1.decentraland.org`
  5. Clique em **Publicar para servidor personalizado**
  6. Aprove a transação como em um deploy normal.

  Para fazer isso via CLI:

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

  Por exemplo:

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

  Veja [catalyst-monitor](https://decentraland.github.io/catalyst-monitor/) para uma verificação de status de todos os servidores na rede catalyst. Você também pode copiar os endereços de cada um, a partir do topo de cada cartão.
* Verifique o status da sua scene `arquivo package.json`. Um problema comum é que existe um `bundleDependencies` e também um `bundledDependencies` (d extra) seção. Isso às vezes pode resultar de executar diferentes versões do Node no mesmo projeto em momentos diferentes, ou de compartilhar o projeto entre pessoas que o executaram com diferentes versões do Node instaladas. Exclua `bundleDependencies`, que se relaciona com versões mais antigas do Node.

Além disso, certifique-se de que a sua versão do Node esteja atualizada, pelo menos a versão 20.

#### Problema: executando `npm run deploy` ou `npm run build` relata erros de tipo

A sua scene pode ter erros de tipo relatados pelo TypeScript, por exemplo indicando que uma determinada variável pode ser do tipo `qualquer` ou que `undefined` ou `null` não são permitidos. Ao executar `npm run deploy`, ele também executa `npm run build`que é um pouco mais rigoroso com essas verificações do que `npm run start`.

Ao contrário do JavaScript, o TypeScript impõe tipagem estrita a todas as variáveis. Mesmo que sua scene esteja escrita de forma que, por exemplo, um determinado valor nunca será `undefined`, o TypeScript precisa saber o que aconteceria nesse cenário, ou você precisa esclarecer explicitamente que o valor só pode ser, por exemplo, uma string.

Como alternativa, você pode executar `npm run deploy -- --skip-build` para pular a execução de `npm run build`, e impedir que essas verificações sejam executadas.

#### Problema: Publiquei minha scene, mas não vejo as mudanças quando entro no Decentraland

* Lembre-se de que isso pode levar alguns minutos se a scene contiver assets pesados.
* Enquanto os modelos 3D da nova versão estão sendo convertidos em asset bundles, os jogadores recebem deliberadamente a última versão totalmente funcional da sua scene. Isso normalmente leva apenas alguns segundos, mas pode demorar mais em scenes muito grandes ou quando os servidores estão ocupados. Você pode [verificar o status da conversão](/creator/content-creator-pt/scene-editor/publicar/publish-scene.md#check-the-conversion-status) da sua scene diretamente.
* Recarregar a scene não é suficiente para obter uma nova versão: um reload reinicia o código da scene, mas não busca a versão recém-publicada. Assim que a conversão for concluída, feche totalmente e reinicie o Decentraland e, em seguida, entre na scene novamente por meio de um jump link ou do `/goto` comando do chat.

#### Problema: Alguns jogadores veem a nova versão da minha scene, outros ainda veem a antiga

A conversão dos modelos 3D da sua scene termina em momentos diferentes para cada plataforma (Windows e Mac), e o client de cada jogador também mantém um cache local. Para verificar se a conversão foi concluída para todas as plataformas, [verificar o status da conversão](/creator/content-creator-pt/scene-editor/publicar/publish-scene.md#check-the-conversion-status) e compare os `valores de windows` e `e mac` em `assetBundles`. Assim que ambos estiverem `complete`prontos, peça aos jogadores afetados que fechem totalmente e reiniciem o Decentraland.

#### Problema: A publicação está travada na etapa Converting, o botão Jump In nunca aparece

Sua scene está na fila atrás de outras scenes sendo convertidas, ou a conversão falhou.

* Open `https://asset-bundle-registry.decentraland.org/queues/status` e procure o ID da entity da sua scene. Você pode encontrar esse ID no campo `entityId` ao [verificar o status da conversão](/creator/content-creator-pt/scene-editor/publicar/publish-scene.md#check-the-conversion-status) usar as coordenadas da sua scene. Se o seu ID estiver listado na fila, a scene está na fila e você só precisa esperar.
* Se ele não estiver na fila, [verificar o status da conversão](/creator/content-creator-pt/scene-editor/publicar/publish-scene.md#check-the-conversion-status) verifique o status da sua scene. Se uma plataforma mostrar `falhou`, publique a scene novamente. Se falhar uma segunda vez, [relate o problema](/creator/content-creator-pt/scenes-sdk7/depuracao/report-bug.md) e inclua o ID da entity.

#### Problema: Depois de fazer deploy, alguns modelos 3D estão ausentes, pretos ou sem textura

* Se você acabou de publicar, a conversão dos seus modelos em asset bundles talvez ainda não tenha terminado. Digite `/detectabs` na janela do chat: modelos tingidos de vermelho ainda não foram convertidos. [Verifique o estado da conversão](/creator/content-creator-pt/scene-editor/publicar/publish-scene.md#check-the-conversion-status) e aguarde a conclusão.
* Certifique-se de que todos os modelos 3D estejam dentro dos limites da scene, inclusive as suas bounding boxes. Se qualquer parte dos seus modelos se estender além desses limites ao executar uma preview, essas partes que se estendem serão cortadas e não renderizadas, tanto ao executar uma preview quanto na scene publicada.
* Se as texturas forem o problema, lembre-se de que as texturas nos modelos 3D têm um tamanho máximo de 1024x1024 pixels durante a conversão.

#### Problema: A scene parece normal de perto, mas fica quebrada ou ausente quando vista de longe

As versões de baixo Level of Detail (LOD) dos seus assets, usadas para renderizar a scene de longe, são geradas na última etapa da publicação e talvez ainda não tenham terminado. Isso não bloqueia testar sua scene de perto. [Verifique o estado da conversão](/creator/content-creator-pt/scene-editor/publicar/publish-scene.md#check-the-conversion-status) e observe os valores em `lods`, ou simplesmente espere e verifique novamente mais tarde.

#### Problema: Depois de fazer deploy, meus modelos 3D parecem diferentes

* Se as texturas parecem diferentes, lembre-se de que as texturas nos modelos 3D têm um tamanho máximo de 1024x1024 pixels. Essa conversão é realizada para garantir que o Decentraland funcione sem problemas para todos.
* Se os modelos parecem diferentes, pode haver um problema na conversão dos modelos para asset bundles. Leia mais sobre a compressão de asset bundle [aqui](/creator/content-creator-pt/scenes-sdk7/otimizacao/performance-optimization.md#asset-bundle-conversion).

  Para validar isso, tente executar a scene com o parâmetro de URL `&DISABLE_ASSET_BUNDLES`. Se os modelos parecerem normais com essa flag, o problema deve estar relacionado a um bug na conversão do modelo. Nesse caso, [relate o problema](/creator/content-creator-pt/scenes-sdk7/depuracao/report-bug.md) e inclua o ID da entity do seu deploy.

  Observe que a geração de versões comprimidas em asset-bundle dos seus modelos leva um pouco de tempo aos servidores (geralmente alguns minutos, mais em scenes muito grandes ou quando os servidores estão ocupados). Você pode verificar se os modelos estão sendo carregados como asset bundles comprimidos ou não escrevendo o seguinte comando na janela do chat `/detectabs`. Os modelos comprimidos são tingidos de verde; os não comprimidos são tingidos de vermelho.

  Você também pode reproduzir essa conversão localmente antes de publicar, ativando [assets otimizados no preview](/creator/content-creator-pt/scenes-sdk7/primeiros-passos/preview-scene.md#preview-with-optimized-assets). Isso permite que você encontre e depure esses problemas sem precisar fazer deploy da scene.

#### Problema: Minha scene desapareceu completamente

* Se a scene estiver em um World: seu orçamento de armazenamento do Worlds pode ter sido excedido, por exemplo após vender ou transferir NAMEs, LAND ou MANA. Você tem 48 horas para liberar espaço ou aumentar seu orçamento antes que seus Worlds se tornem inacessíveis. Verifique seu orçamento na **Gerenciar** aba do Creator Hub ou no **Worlds** do [Builder](https://decentraland.org/builder/worlds), depois publique novamente. Veja [limites de tamanho dos Worlds](/creator/content-creator-pt/scenes-sdk7/tipos-de-projetos/kinds-of-project.md#size-limits).
* Se a scene estiver em LAND: alguém com permissões de deploy pode ter publicado uma nova scene sobre os seus parcels, apagando o conteúdo anterior. Veja [sobrescrita de scene](/creator/content-creator-pt/scenes-sdk7/publicacao/publishing.md#scene-overwriting).
* Em casos raros, conteúdo que viole a política de conteúdo do Decentraland pode ser colocado na denylist dos content servers. Se você acredita que isso aconteceu por engano, entre em contato por meio do [Discord da Decentraland](https://decentraland.org/discord).

#### Problema: Minha scene tem FPS baixo em produção, mesmo que funcione suavemente no preview.

O desempenho da sua scene pode ser afetado por scenes vizinhas que seguem más práticas, já que elas também executam em paralelo. Você pode validar que esse é o caso abrindo as configurações e definindo a linha de visão para o mínimo, para que apenas 1 parcel ao redor da sua scene atual seja carregado.

Você pode reduzir ainda mais a linha de visão executando sua scene com o parâmetro `&LOS=0`, para não carregar nenhuma scene ao redor.

Se você acabou de fazer deploy da sua scene, a carga ao carregá-la também pode ser reduzida assim que os servidores converterem os modelos 3D da scene em asset bundles comprimidos. Você pode verificar se os modelos estão sendo carregados como asset bundles comprimidos ou não escrevendo o seguinte comando na janela do chat `/detectabs`. Os modelos comprimidos são tingidos de verde; os não comprimidos são tingidos de vermelho.

### Relatar um bug

Se você encontrar um problema que não seja com sua cena, mas sim com o SDK do Decentraland em geral, consulte [Relatar um bug](/creator/content-creator-pt/scenes-sdk7/depuracao/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-pt/scenes-sdk7/depuracao/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.