> 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-es/scenes-sdk7/depuracion/troubleshooting.md).

# Solución de problemas

Soluciones para problemas comunes

## Depurar con un asistente de IA

Antes de revisar los problemas que aparecen a continuación, considera pasarle el problema a un asistente de IA, como el chat de Cursor, GitHub Copilot o Claude Code. Pega el mensaje de error de la consola o describe qué no está funcionando como esperabas; normalmente podrá encontrar el problema en el código de tu Scene y corregirlo.

Para obtener buenos resultados, asegúrate de que la IA tenga instaladas las habilidades de Decentraland SDK. Estas habilidades le enseñan los patrones y las limitaciones del SDK, para que no haga conjeturas basadas en información genérica o desactualizada. Instálalas ejecutando este comando en el proyecto de tu Scene:

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

Consulta [Programación intuitiva con IA](https://docs.decentraland.org/creator/content-creator-es/scenes-sdk7/primeros-pasos/vibe-coding.md) para obtener más información sobre cómo configurar y dar instrucciones a los asistentes de IA.

También puedes dejar que la IA depure la Scene *mientras se está ejecutando*. El cliente de escritorio de Decentraland puede exponer un servidor MCP que permite a un agente tomar capturas de pantalla, leer la salida de la consola de la Scene, mover al jugador y hacer clic en objetos. Así, en vez de reproducir el error y pegarlo, el agente lo reproduce por su cuenta, observa qué ocurre y lo intenta de nuevo hasta corregirlo. Inicia la Scene con `npm run start -- --mcp` y conecta tu agente a él.

Consulta [Permitir que la IA vea tu Scene dentro del mundo](https://docs.decentraland.org/creator/content-creator-es/scenes-sdk7/primeros-pasos/vibe-coding.md#let-the-ai-see-your-scene-in-world) para ver la configuración completa e instala la habilidad `unity-explorer-mcp` para que el agente conozca el flujo de trabajo:

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

## Problemas al ejecutar la vista previa

#### Problema: No se puede ejecutar la vista previa de ninguna Scene; el mensaje de error menciona **Permiso denegado** o **EACCES**

Tu sistema operativo no te permite cambiar los permisos de la carpeta en la que quieres ejecutar el proyecto. Al ejecutar la Scene, es necesario instalar algunas dependencias, pero no está permitido. Debes configurar los permisos de la carpeta para que tu cuenta de usuario de Windows/Mac/Linux pueda editar los archivos que contiene.

Recursos útiles:

* [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: No se puede ejecutar la vista previa de una Scene en particular; el error dice **Error: Error al compilar el proyecto**

Si vas a ejecutar una Scene que alguien compartió contigo, asegúrate de que no se haya compartido con una carpeta `node_modules` o `bin` ni con un archivo `package-lock.json` . Estos archivos contienen dependencias con versiones específicas para tu sistema operativo y equipo; deben generarse la primera vez que se ejecuta la Scene. Elimina manualmente estas carpetas y este archivo; luego ejecuta `npm run start` de nuevo.

#### Problema: Al ejecutar `npm run start` el comando se ejecuta sin mostrar ningún mensaje de error, pero no se abre ninguna ventana del navegador ni aparece una URL en la salida para abrir la vista previa

Asegúrate de tener una versión actualizada de Node. Debe ser la versión 20 o posterior.

#### Problema: Al ejecutar `npm run start` se abre una pestaña del navegador, pero la pantalla de carga nunca termina de cargar o aparece un banner de error rojo que dice «error crítico».

* Asegúrate de tener instalada en tu proyecto la versión más reciente de Decentraland SDK. Ejecuta:

  `npm i @dcl/sdk@latest`

#### Problema: La Scene se ejecuta y en la consola aparecen advertencias de `Cyclic dependencies` .

Estas advertencias hacen referencia a archivos de tu Scene que se referencian mutuamente. No necesariamente es un problema, pero no es un patrón recomendado para escribir software, ya que puede provocar condiciones de carrera difíciles de depurar y otros problemas. Es probable que tu Scene funcione bien a pesar de estas advertencias.

Lo ideal es que la carga del código de tu Scene siga un orden secuencial claro. El código con dependencias cíclicas puede tener un problema del huevo y la gallina, en el que el compilador no sabe qué debe inicializar primero. A menudo esto se resuelve sin problemas, pero es una buena práctica evitarlo.

Para solucionar estas dependencias, a menudo tendrás que recurrir a llamar funciones o constructores de objetos pasando referencias a entidades/objetos ya instanciados como argumentos de la función, en lugar de codificar directamente en la función referencias a estas entidades/objetos, que quizá ya estén instanciados o quizá no.

## Problemas al publicar

#### Problema: No tienes permisos para publicar en estas parcelas

* Asegúrate de que el `scene.json` de tu Scene indique correctamente las coordenadas en las que quieres publicar.
* Asegúrate de que Metamask esté configurado correctamente para usar la Wallet adecuada al firmar la transacción. Puede ser la Wallet propietaria de los tokens LAND o una Wallet a la que el propietario haya concedido permisos de operador.

#### Problema: Al ejecutar `npm run deploy` se produce un error

* Comprueba los puntos de aparición de tu Scene: las tres coordenadas x, y, z de cada punto de aparición deben ser números o rangos. Las tres deben ser números o las tres deben ser rangos. No se admite combinar rangos para algunas coordenadas y números para las demás.

  Por ejemplo, esto no es compatible:

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

  Esto sí es compatible:

  `"position": {"x": [1,4], "y": [0,0], "z": [1,4]}`
* Es posible que el servidor Catalyst predeterminado al que se te asigna para publicar no funcione o tenga problemas. Puedes hacer que el comando `npm run deploy` publique en un servidor Catalyst específico. Para publicar en un servidor específico desde Decentraland Editor:

  1. Abre tu Scene y haz clic en **Publicar**
  2. Selecciona la opción **Publicar en otro servidor** en la parte inferior.
  3. En el Dropdown, selecciona **Servidor personalizado**
  4. Introduce la dirección del servidor, por ejemplo: `peer-ec1.decentraland.org`
  5. Haz clic en **Publicar en un servidor personalizado**
  6. Aprueba la transacción como en una publicación normal.

  Para hacerlo mediante la CLI:

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

  Por ejemplo:

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

  Consulta [catalyst-monitor](https://decentraland.github.io/catalyst-monitor/) para comprobar el estado de todos los servidores de la red Catalyst. También puedes copiar las direcciones de cada uno desde la parte superior de cada tarjeta.
* Comprueba el `package.json`. Un problema habitual es que haya una sección `bundleDependencies` y también una sección `bundledDependencies` (con una d adicional). A veces esto ocurre al usar distintas versiones de Node en el mismo proyecto en diferentes momentos, o al compartir el proyecto entre personas que lo ejecutaron con distintas versiones de Node instaladas. Elimina `bundleDependencies`, que corresponde a versiones anteriores de Node.

Asegúrate también de tener una versión actualizada de Node, como mínimo la versión 20.

#### Problema: La publicación en un World falla con un límite de tamaño de 0 bytes

El mensaje completo dice: «La publicación es demasiado grande. El tamaño total máximo permitido para las Scenes es de 0 bytes». Esto significa que los Worlds de tu Wallet ya utilizan todo el espacio de almacenamiento disponible, por lo que no queda espacio para ninguna carga, por pequeña que sea. Reducir el tamaño de esta Scene no servirá de ayuda.

El servidor de Worlds contabiliza todo lo que has publicado en tus Worlds, menos las Scenes que sustituye esta publicación. Para volver a publicar:

* Libera espacio: anula la publicación de otro World o de otras Scenes de este World desde la página [Administrar](https://docs.decentraland.org/creator/content-creator-es/scene-editor/publicar/manage-lands-and-worlds.md#world-storage-budget) del Creator Hub.
* O amplía tu presupuesto: consigue más NAMEs, LAND o MANA.

Superar el presupuesto también inicia el período de gracia de 48 horas para tus otros Worlds. Consulta [Límites de tamaño de Worlds](https://docs.decentraland.org/creator/content-creator-es/scenes-sdk7/tipos-de-proyectos/kinds-of-project.md#size-limits).

Esto solo se aplica a los Worlds asociados a NAMEs de Decentraland. Los Worlds asociados a dominios ENS tienen un límite fijo por World.

#### Problema: al ejecutar `npm run deploy` o `npm run build` se notifican errores de tipos

Es posible que TypeScript notifique errores de tipos en tu escena; por ejemplo, que una variable determinada podría ser de tipo `any` o que `undefined` o `null` no están permitidos. Al ejecutar `npm run deploy`, también se ejecuta `npm run build`, que aplica estas comprobaciones con un poco más de rigor que `npm run start`.

A diferencia de JavaScript, TypeScript aplica un tipado estricto a todas las variables. Aunque tu escena esté escrita de manera que, por ejemplo, un valor determinado nunca será `undefined`, TypeScript necesita saber qué ocurriría en ese caso, o debes aclarar explícitamente que el valor solo puede ser, por ejemplo, una cadena de texto.

Como alternativa, puedes ejecutar `npm run deploy -- --skip-build` para omitir la ejecución de `npm run build`, y evitar que se realicen estas comprobaciones.

#### Problema: publiqué mi escena, pero no veo los cambios al entrar en Decentraland

* Ten en cuenta que, si la escena contiene recursos pesados, el proceso puede tardar unos minutos.
* Mientras los modelos 3D de la nueva versión se convierten en paquetes de recursos, los jugadores reciben deliberadamente la última versión de la escena que funciona correctamente. Esto suele tardar solo unos segundos, pero puede llevar más tiempo en escenas muy grandes o cuando los servidores están ocupados. Puedes [consultar el estado de conversión](https://docs.decentraland.org/creator/content-creator-es/scene-editor/publicar/publish-scene.md#check-the-conversion-status) de tu escena directamente.
* Recargar la escena no basta para obtener una nueva versión: al recargar, se reinicia el código de la escena, pero no se obtiene la versión recién publicada. Cuando termine la conversión, cierra Decentraland por completo y vuelve a iniciarlo; luego, vuelve a entrar en la escena mediante un enlace de salto o el `/goto` comando de chat.

#### Problema: algunos jugadores ven la nueva versión de mi escena y otros siguen viendo la anterior

La conversión de los modelos 3D de tu escena termina en momentos distintos para cada plataforma (Windows y Mac), y el cliente de cada jugador también conserva una caché local. Para comprobar si la conversión finalizó en todas las plataformas, [consulta el estado de conversión](https://docs.decentraland.org/creator/content-creator-es/scene-editor/publicar/publish-scene.md#check-the-conversion-status) y compara los valores de `windows` y `mac` en `assetBundles`. Cuando ambos estén `complete`, pide a los jugadores afectados que cierren Decentraland por completo y lo vuelvan a iniciar.

#### Problema: la publicación se queda atascada en la etapa de conversión y el botón «Jump In» nunca aparece

Tu escena está en cola detrás de otras escenas que se están convirtiendo, o bien la conversión ha fallado.

* Abre `https://asset-bundle-registry.decentraland.org/queues/status` y busca el ID de entidad de tu escena. Puedes encontrar ese ID en el campo `entityId` cuando [consultas el estado de conversión](https://docs.decentraland.org/creator/content-creator-es/scene-editor/publicar/publish-scene.md#check-the-conversion-status) usando las coordenadas de tu escena. Si tu ID aparece en la cola, la escena está en espera y solo tienes que esperar.
* Si no aparece en la cola, [consulta el estado de conversión](https://docs.decentraland.org/creator/content-creator-es/scene-editor/publicar/publish-scene.md#check-the-conversion-status) de tu escena. Si alguna plataforma muestra `failed`, vuelve a publicar la escena. Si falla por segunda vez, [informa del problema](https://docs.decentraland.org/creator/content-creator-es/scenes-sdk7/depuracion/report-bug.md) e incluye el ID de entidad.

#### Problema: después del despliegue, faltan algunos modelos 3D, aparecen en negro o no tienen texturas

* Si acabas de publicar, es posible que la conversión de tus modelos en asset bundles aún no haya terminado. Escribe `/detectabs` en la ventana de chat: los modelos teñidos de rojo aún no se han convertido. [Consulta el estado de conversión](https://docs.decentraland.org/creator/content-creator-es/scene-editor/publicar/publish-scene.md#check-the-conversion-status) y espera a que finalice.
* Asegúrate de que todos los modelos 3D estén dentro de los límites de la escena, incluidos sus cuadros delimitadores. Si alguna parte de tus modelos sobrepasa estos límites al ejecutar una vista previa, esas partes se recortarán y no se renderizarán, tanto en la vista previa como en la escena publicada.
* Si el problema está en las texturas, ten en cuenta que durante la conversión las texturas de los modelos 3D se limitan a un tamaño máximo de 1024x1024 píxeles.

#### Problema: la escena se ve bien de cerca, pero aparece dañada o incompleta a la distancia

Las versiones con nivel de detalle bajo (LOD) de tus recursos, que se usan para renderizar la escena desde lejos, se generan en la última etapa de la publicación y es posible que aún no estén listas. Esto no impide probar la escena de cerca. [Consulta el estado de conversión](https://docs.decentraland.org/creator/content-creator-es/scene-editor/publicar/publish-scene.md#check-the-conversion-status) y revisa los valores de `lods`, o simplemente espera y vuelve a consultarlo más tarde.

#### Problema: después del despliegue, mis modelos 3D se ven distintos

* Si las texturas se ven distintas, ten en cuenta que las texturas de los modelos 3D se limitan a un tamaño máximo de 1024x1024 píxeles. Esta conversión se realiza para garantizar que Decentraland funcione correctamente para todos.
* Si los modelos se ven distintos, puede haber un problema con su conversión en asset bundles. Obtén más información sobre la compresión de asset bundles [aquí](https://docs.decentraland.org/creator/content-creator-es/scenes-sdk7/optimizacion/performance-optimization.md#asset-bundle-conversion).

  Para comprobarlo, intenta ejecutar la escena con el parámetro de URL `&DISABLE_ASSET_BUNDLES`. Si los modelos se ven bien con esta opción, el problema debe estar relacionado con un error en la conversión del modelo. En ese caso, [informa del problema](https://docs.decentraland.org/creator/content-creator-es/scenes-sdk7/depuracion/report-bug.md) e incluye el ID de entidad de tu despliegue.

  Ten en cuenta que los servidores tardan un poco en generar versiones comprimidas de tus modelos en asset bundles (normalmente unos minutos, aunque puede llevar más tiempo con escenas muy grandes o cuando los servidores están ocupados). Para comprobar si los modelos se están cargando como asset bundles comprimidos, escribe el siguiente comando en la ventana de chat: `/detectabs`. Los modelos comprimidos aparecen teñidos de verde y los que no están comprimidos, de rojo.

  Desktop Explorer realiza la misma conversión localmente cuando [previsualizas tu escena](https://docs.decentraland.org/creator/content-creator-es/scenes-sdk7/primeros-pasos/preview-scene.md#preview-with-optimized-assets), así que puedes detectar estos problemas sin desplegarla. Para comparar, vuelve a previsualizar con la opción **Load Raw GLTFs** activada: si los modelos se ven bien así, el problema está en la conversión.

#### Problema: mi escena ha desaparecido por completo

* Si la escena está en un World: es posible que hayas superado el límite de almacenamiento de tus Worlds, por ejemplo, después de vender o transferir NAMEs, LAND o MANA. Tienes 48 horas para liberar espacio o aumentar el límite antes de que tus Worlds dejen de estar accesibles. Consulta tu límite en **Manage** pestaña del Creator Hub o en la **Worlds** pestaña del [Builder](https://decentraland.org/builder/worlds), y vuelve a publicar. Consulta [Límites de tamaño de Worlds](https://docs.decentraland.org/creator/content-creator-es/scenes-sdk7/tipos-de-proyectos/kinds-of-project.md#size-limits).
* Si la escena está en LAND: alguien con permisos de despliegue podría haber publicado una escena nueva sobre tus parcelas, lo que borra el contenido anterior. Consulta [sobrescritura de escenas](https://docs.decentraland.org/creator/content-creator-es/scenes-sdk7/publicacion/publishing.md#scene-overwriting).
* En casos excepcionales, el contenido que infrinja la política de contenido de Decentraland puede incluirse en una lista de bloqueo de los servidores de contenido. Si crees que esto ocurrió por error, comunícate a través de [Discord de Decentraland](https://decentraland.org/discord).

#### Problema: Mi escena tiene pocos FPS en producción, aunque funciona sin problemas en la vista previa.

El rendimiento de tu escena podría verse afectado por escenas vecinas que siguen prácticas deficientes, ya que también se ejecutan en paralelo. Puedes comprobar si este es el caso abriendo la configuración y reduciendo al mínimo la línea de visión, de modo que solo se cargue 1 parcela alrededor de tu escena actual.

Puedes reducir aún más la línea de visión ejecutando tu escena con el parámetro `&LOS=0`, para no cargar ninguna escena del entorno.

Si acabas de desplegar tu escena, es posible que la carga de la escena también mejore cuando los servidores conviertan los modelos 3D de la escena en paquetes de recursos comprimidos. Puedes comprobar si los modelos se cargan como paquetes de recursos comprimidos o no escribiendo el siguiente comando en la ventana del chat `/detectabs`. Los modelos comprimidos aparecen teñidos de verde y los no comprimidos, de rojo.

### Informar de un error

Si encuentras un problema que no esté relacionado con tu escena, sino con el SDK de Decentraland en general, consulta [Informar de un error](https://docs.decentraland.org/creator/content-creator-es/scenes-sdk7/depuracion/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-es/scenes-sdk7/depuracion/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.
