Un secreto o una referencia no aparece en mi servicio

Configuraste un secreto o una referencia ${{name.KEY}}, volviste a desplegar y el servicio en ejecución sigue sin ver el valor que esperas.

Qué significa esto

El valor que configuraste nunca llegó al entorno combinado del servicio, o algo más en la combinación lo sobrescribió antes de que la app se iniciara.

Por qué puede pasar esto

• El destino o la clave de la referencia no existen. Una referencia a un nombre de servicio/addon que no existe, o a una clave que ese addon no expone, se resuelve como una cadena vacía en lugar de hacer fallar el despliegue. El log de compilación muestra un aviso por cada referencia vacía, con el motivo; un cambio de variables aplicado con un reinicio, sin compilación, no muestra ningún aviso. Un destino al que le cambiaste el nombre cuenta como inexistente para las referencias definidas con lizard secrets set o el dashboard: coinciden con el nombre actual. Un servicio de destino no expone el DATABASE_URL ni el REDIS_URL que Lizard le inyecta; haz referencia al addon en su lugar.
• Algo con mayor precedencia lo sobrescribió. Los valores se combinan en un orden fijo — addon-issued env < project secrets < project env < app env < app secrets < platform vars — así que un secreto con alcance de proyecto (--global) puede quedar oculto silenciosamente por uno con alcance de servicio con la misma clave, y las variables de la plataforma (PORT, LIZARD_SERVICE_NAME, LIZARD_PROJECT_ID, LIZARD_PUBLIC_DOMAIN, LIZARD_PRIVATE_DOMAIN) siempre prevalecen. Un PORT que definas tú solo cambia el puerto al que Lizard dirige el tráfico en un servicio cuyo puerto nunca se fijó. En un servicio creado por lizard up, o con un puerto fijado mediante --port, lizard port o el dashboard, Lizard lo sobrescribe; cambia el puerto con lizard port <n>.
• Un valor de tiempo de compilación no llegó a la compilación. La mayoría de los cambios de variables se aplican sin recompilar: el servicio se reinicia para tomarlos. Los valores de VITE_* y NEXT_PUBLIC_* quedan integrados en los recursos compilados, y cambiar uno con lizard secrets set o en la configuración de un servicio inicia al momento una recompilación de los servicios en marcha. Un cambio en la página Secrets del proyecto en el dashboard no inicia ninguna recompilación. Un servicio que en ese momento había fallado o estaba detenido se omite, y un servicio con un dockerfilePath personalizado o subido con lizard up sin comandos de compilación/inicio nunca recibe estos valores en la compilación.

Posibles soluciones

Busca referencias vacías en el log de compilación

El acceso por shell a los servicios (lizard ssh) está desactivado. El log de compilación es el lugar donde mirar: cada referencia vacía recibe una línea como ==> Warning: ... is empty con el motivo.

lizard logs --build --service api

Después, lista las claves de los addons y las claves LIZARD_* y PORT de cada servicio, y compara el nombre y la clave con los tuyos. Las referencias a las variables y los secretos propios de otro servicio funcionan, pero no aparecen en la lista; compruébalos con lizard secrets list --service <target>. Comprueba las claves en las variables documentadas del addon:

lizard secrets list --service api --ref

Comprueba si hay una colisión de alcance

Enumera los secretos en ambos alcances y compáralos:

lizard secrets list --service api --show
lizard secrets list --global --show

Recuerda que los secretos de la app sobrescriben los secretos del proyecto: si existe un valor con alcance de servicio para la misma clave, prevalece sobre cualquier cosa configurada con --global.

Recompila después de un cambio en tiempo de compilación

Si la clave modificada es VITE_* o NEXT_PUBLIC_*, y el servicio había fallado o estaba detenido cuando la cambiaste o la cambiaste en la página Secrets del proyecto en el dashboard, activa una recompilación:

lizard redeploy --service api

Consulta Tiempo de compilación vs. tiempo de ejecución y Proceso de compilación → qué activa una recompilación.

Ver también

• Variables y secretos — alcance y precedencia.
• Referencias entre servicios — sintaxis de referencia y resolución.

Actualizado 21 de octubre de 2026