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: las referencias coinciden con el nombre actual.
• 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. Si defines PORT tú mismo, lo que cambias es el puerto al que Lizard dirige el tráfico, salvo que el puerto se haya fijado con lizard port.
• 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 inicia al momento una recompilación de los servicios en marcha. 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 plantillas de referencia válidas en este alcance y compara el nombre y la clave con los tuyos. 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, 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 9 de octubre de 2026