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

# Solución de problemas

## Depura con un asistente de IA

Antes de revisar los problemas de abajo, 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 console, o describe qué no está funcionando como esperas, y por lo general puede encontrar el problema en el código de tu escena y corregirlo por ti.

Para obtener buenos resultados, asegúrate de que el asistente de IA tenga instaladas las skills de Decentraland SDK. Las skills le enseñan los patrones y restricciones del SDK, para que no adivine basándose en información genérica o desactualizada. Instálalas ejecutando este comando en el proyecto de tu escena:

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

Consulta [Vibe Coding con IA](/creator/content-creator-es/escenas-sdk7/primeros-pasos/vibe-coding.md) para más detalles sobre cómo configurar y dar prompts a asistentes de IA.

También puedes dejar que la IA depure la escena *mientras se ejecuta*. El cliente de escritorio de Decentraland puede exponer un servidor MCP que permite a un agente tomar sus propias capturas de pantalla, leer la salida de la console de la escena, mover al jugador y hacer clic en objetos; así que, en lugar de que tú reproduzcas el error y pegues el mensaje, el agente lo reproduce por sí mismo, ve qué sucede e itera hasta que quede resuelto. Inicia la escena con `npm run start -- --mcp` y conecta tu agente a él.

Consulta [Deja que la IA vea tu escena en el mundo](/creator/content-creator-es/escenas-sdk7/primeros-pasos/vibe-coding.md#let-the-ai-see-your-scene-in-world) para la configuración completa, e instala la skill `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 preview

#### Problema: No puedo ejecutar ningún preview de escena, el mensaje de error menciona **Permissions denied** o **EACCES**

Tu sistema operativo no te permite editar permisos en la carpeta donde quieres ejecutar el proyecto. Al ejecutar la escena, algunas dependencias necesitan instalarse, pero está prohibido. Debes configurar los permisos de la carpeta para permitir que tu cuenta de usuario de Windows/Mac/Linux edite archivos en ella.

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 puedo ejecutar el preview de una escena concreta, el error dice **Error: Error al compilar el proyecto**

Si estás ejecutando una escena que te compartieron, asegúrate de que esta escena no se haya compartido incluyendo una carpeta `node_modules` o `bin` o un archivo `package-lock.json` . Estos archivos contienen dependencias que usan versiones específicas para tu SO y tu máquina; deben generarse al ejecutar la escena por primera vez. Elimina estas carpetas y este archivo manualmente, luego ejecuta `npm run start` de nuevo.

#### Problema: Ejecutar `npm run start` se ejecuta, no hay mensaje de error, pero no se abre ninguna ventana del navegador ni aparece ninguna URL en la salida para abrir el preview

Asegúrate de que tu versión de Node esté actualizada. Debe ser 20 o superior.

#### Problema: Ejecutar `npm run start` abre una pestaña del navegador, pero la pantalla de carga nunca termina de cargar, o veo un banner de error rojo que dice "critical error".

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

  `npm i @dcl/sdk@latest`

#### Problema: La escena se ejecuta, en la console veo `Dependencias cíclicas` advertencias.

Esto se refiere a archivos de tu escena que se referencian entre sí de forma mutua. Esto no es necesariamente un problema, pero no es un patrón recomendable para escribir software, ya que puede provocar condiciones de carrera y otros problemas difíciles de depurar. Es probable que tu escena funcione bien a pesar de estas advertencias.

Idealmente, la carga del código en tu escena debería seguir un orden secuencial claro. El código que tiene dependencias cíclicas puede sufrir un problema del huevo y la gallina, donde el compilador no sabe cuál iniciar primero. A menudo esto se resuelve sin problemas, pero es una buena práctica evitarlo.

Para corregir estas dependencias, a menudo debes recurrir a llamar funciones o constructores de objetos pasando referencias a entidades/objetos ya instanciados en los argumentos de la función; en lugar de codificar de forma rígida referencias a estas entidades/objetos en la función, que pueden o no estar ya instanciados.

## Problemas al deployar

#### Problema: No tienes permisos para deployar en estos parcels

* Asegúrate de que el archivo `scene.json` de tu escena enumere correctamente las coordenadas donde quieres deployar.
* Asegúrate de que Metamask esté correctamente configurado para usar la wallet adecuada para firmar la transacción. Esta puede ser la wallet que posee los tokens LAND, o puede tener permisos de operador concedidos por el propietario.

#### Problema: Ejecutar `npm run deploy` falla

* Revisa los spawn points de tu escena: las tres coordenadas x, y, z de un spawn point deben ser un número o un rango. O bien las tres son números, o bien las tres son rangos. No se admite tener rangos para unas y números para otras.

  Por ejemplo, esto no se admite:

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

  Esto sí se admite:

  `"position": {"x": [1,4], "y": [0,0], "z": [1,4]}`
* Es posible que el servidor catalyst predeterminado al que se te asignó deployar esté caído o tenga problemas. Puedes forzar el comando `npm run deploy` para deployar en su lugar en un servidor catalyst específico. Para deployar en un servidor específico en el Decentraland Editor:

  1. Abre tu escena y haz clic en **Publish**
  2. Selecciona la opción **Publish to a different server** en la parte inferior.
  3. En el desplegable, selecciona **Custom Server**
  4. Introduce la dirección del servidor, por ejemplo `peer-ec1.decentraland.org`
  5. Haz clic en **Publish to custom server**
  6. Aprueba la transacción como en un deploy 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.
* Revisa el `package.json`. Un problema común es que haya una sección `bundleDependencies` y también una `bundledDependencies` (con una d extra). Esto a veces puede resultar de ejecutar distintas versiones de Node en el mismo proyecto en momentos diferentes, o de compartir el proyecto entre personas que lo ejecutaron con distintas versiones de Node instaladas. Elimina `bundleDependencies`, que se relaciona con versiones antiguas de Node.

Asegúrate también de tener tu versión de Node actualizada, al menos la versión 20.

#### Problema: Ejecutar `npm run deploy` o `npm run build` informa errores de tipos

Tu escena podría tener errores de tipos informados por TypeScript, por ejemplo indicando que una determinada variable 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 es un poco más estricto con estas comprobaciones que `npm run start`.

A diferencia de JavaScript, TypeScript impone un tipado estricto para todas las variables. Aunque tu escena esté escrita de forma que, por ejemplo, cierto valor nunca sea `undefined`, TypeScript necesita saber qué ocurriría en ese escenario, o debes aclarar explícitamente que el valor solo puede ser, por ejemplo, una string.

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

#### Problema: He deployado mi escena pero no veo los cambios cuando entro en Decentraland

* Ten en cuenta que puede tardar unos minutos en propagarse el contenido nuevo por todos los servidores de la red catalyst; dale un poco de tiempo.

#### Problema: Una vez deployado, faltan algunos modelos 3D

* Asegúrate de que todos los modelos 3D estén dentro de los límites de la escena, incluso sus cajas delimitadoras. Si alguna parte de tus modelos se extiende más allá de estos límites al ejecutar un preview, esas partes extendidas se recortarán y no se renderizarán, tanto al ejecutar un preview como en la escena publicada.

#### Problema: Una vez deployados, mis modelos 3D se ven diferentes

* Si las texturas se ven diferentes, ten en cuenta que las texturas de los modelos 3D tienen un tamaño máximo de 512x512 píxeles. Esta conversión se realiza para garantizar que Decentraland funcione sin problemas para todos.
* Si los modelos se ven diferentes, podría haber un problema con la conversión de los modelos a asset bundles. Lee más sobre la compresión de asset bundles [aquí](/creator/content-creator-es/escenas-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 este indicador, el problema debe estar relacionado con un fallo en la conversión del modelo.

  Ten en cuenta que la generación de versiones comprimidas de asset-bundle de tus modelos es un proceso que toma tiempo a los servidores (aproximadamente una hora). Puedes comprobar si los modelos se están cargando como asset bundles comprimidos o no escribiendo el siguiente comando en la ventana de chat `/detectabs`. Los modelos comprimidos se tiñen de verde; los no comprimidos, de rojo.

#### Problema: Mi escena tiene un FPS bajo en producción, aunque se ejecuta con fluidez en preview.

El rendimiento de tu escena podría verse afectado por escenas vecinas que siguen malas prácticas, ya que también se ejecutan en paralelo. Puedes validar que ese es el caso abriendo los settings y estableciendo la línea de visión al mínimo, de modo que solo se cargue 1 parcel 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 circundante en absoluto.

Si acabas de deployar tu escena, la carga al cargar la escena también podría reducirse una vez que los servidores conviertan los modelos 3D de la escena en asset bundles comprimidos. Puedes comprobar si los modelos se están cargando como asset bundles comprimidos o no escribiendo el siguiente comando en la ventana de chat `/detectabs`. Los modelos comprimidos se tiñen de verde; los no comprimidos, de rojo.

### Reportar un error

Si encuentras un problema que no está en tu escena, sino en el Decentraland SDK en general, consulta [Reportar un error](/creator/content-creator-es/escenas-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 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-es/escenas-sdk7/depuracion/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.