Errores comunes — código, qué significa y cómo se arregla

Cada error del sistema es un código snake_case estable. Aquí están los más frecuentes con el fix exacto.

Publicación (validación del manifest)

Código	Significa	Fix
`manifest_invalid`	El JSON no parsea o no cumple el esquema raíz.	Valida el JSON; revisa comas y comillas.
`app_id_invalid`	El `appId` no cumple el formato.	Usa `^[a-z0-9][a-z0-9.-]{2,99}$` (minúsculas, 3–100 chars).
`app_id_immutable`	El `appId` del manifest difiere del de la app.	El `appId` es inmutable; no lo cambies entre versiones.
`semver_not_increasing`	La versión es ≤ a la última publicada.	Sube la versión (semver estrictamente creciente).
`roblox_requires_cloud_relay`	`platform: roblox` sin `cloud-relay`.	Pon `transport: "cloud-relay"`.
`config_default_required`	Un campo de config no tiene `default`.	Agrega `default` a TODOS los campos de config.
`config_type_changed`	Un `key` cambió de `type` entre versiones.	Usa un `key` nuevo en vez de cambiar el tipo del existente.
`cover_required`	Falta la carátula o no coincide el nombre.	Sube la carátula; `coverImage` debe ser el nombre del archivo subido.
`categories_count_invalid`	Fuera del rango 1–3 categorías.	Elige entre 1 y 3 categorías.
`source_github_required`	`web` sin `hostedUploads` y sin `source.type: github`.	Usa origen GitHub, o pide el flag de subidas hospedadas.
`github_source_incomplete`	Faltan `repo`/`branch`/`path`.	Completa los tres campos del origen GitHub.

Código	Significa	Fix
`app_not_allowed`	El streamer no aprobó tu app en el agente.	Pídele que acepte el prompt de permisos (o que active el modo dev para probar).
`app_not_published`	La app aún no está publicada/aprobada.	Espera la aprobación, o usa el modo dev del agente para desarrollo.

No llegan eventos con npm run dev: asegúrate de correr también npm run mock en otra terminal. Sin el mock (o sin estar en vivo con el agente) no hay fuente de eventos.
El juego no aparece en el preview demo: revisa que respondas tx:ready a los mensajes postMessage del parent cuando la URL trae ?txmode=demo. El SDK lo hace por ti con createClient().
Los gifts se disparan de más: cuenta el streak SOLO cuando streakEnd es true. En v1 siempre llega true, pero escríbelo defensivamente para v2.