Solución de problemas

Soluciones orientadas a tareas para los problemas con los que te vas a encontrar de verdad: una fórmula en blanco, un código de error de Excel, un agent que no reconecta, y fallos de inscripción — más dónde mirar para saber más.

Mi fórmula está en blanco

Con diferencia la sorpresa más común, y casi siempre la misma causa: no has publicado. Editar una conexión, función, botón de la cinta o panel de tareas solo cambia el borrador de trabajo del entorno — no llega a Excel hasta que lo publicas deliberadamente.

Abre la página Versions del entorno y revisa el banner. Un banner ámbar de "cambios sin publicar" significa que el borrador y la versión en vivo son distintos.
Haz clic en Save version, mantén "Make this version live" marcado, y guarda.
Recalcula el libro. La fórmula debería resolverse ahora.

Si el banner está azul (nada sin publicar) y la fórmula sigue en blanco, confirma que la función realmente existe en el entorno contra el que estás probando — los entornos que no son de producción llevan como sufijo el espacio de nombres (=NAMESPACE_DEV.MODULE.FN(…) para Development, _QA para QA, y así sucesivamente), así que un libro conectado al espacio de nombres del entorno equivocado nunca encontrará la función. Consulta Versiones para el modelo completo de borrador/en vivo.

Códigos de error de Excel

Estos son los propios valores de error de Excel, mostrados en la celda — no es algo que ConnXL invente. Esto es lo que significa cada uno cuando viene de una función de ConnXL, y qué revisar.

Field	Type	Description
`#GETTING_DATA`Optional	`transitorio`	Normal, no es un error: una función asíncrona todavía está esperando al agent. Se resuelve solo en cuanto termina la llamada. Solo persiste indefinidamente si el agent es inalcanzable o la llamada se cuelga — comprueba que el agent esté en línea y que la conexión de la que depende responda.
`#SPILL!`Optional	`desborde bloqueado`	Una función que devuelve varias filas/columnas necesita celdas vacías donde desbordarse, y algo ocupa ese rango. Vacía las celdas debajo y a la derecha de la fórmula, o mueve la fórmula a un sitio con espacio.
`#BUSY!`Optional	`registro obsoleto`	Excel se ha quedado atascado en un registro antiguo de funciones personalizadas para el espacio de nombres — normalmente un resto de una versión anterior del manifiesto. Cierra Excel por completo, borra su caché de complementos, y vuelve a abrirlo (Windows: borra el contenido de `%LOCALAPPDATA%\Microsoft\Office\16.0\Wef\`; en la web, haz un refresco forzado). Volver a hacer sideload tras un cambio de manifiesto (un botón de cinta nuevo, un icono, o una acción ExecuteFunction) suele ser el disparador.
`#NAME?`Optional	`función no reconocida`	Excel no reconoce el nombre de la fórmula en absoluto. Revisa el espacio de nombres (recuerda que los entornos que no son de producción llevan sufijo, p. ej. NAMESPACE_DEV), la ortografía del módulo y la función, y que el manifiesto de este entorno realmente se haya instalado — un cambio de manifiesto (los nombres de función nuevos aparecen mediante metadatos regenerados, pero un cambio de espacio de nombres o de identidad del complemento necesita un sideload nuevo) requiere reinstalar.
`#VALUE!`Optional	`argumento inválido`	La función recibió un argumento del tipo equivocado o un valor inválido — un texto donde se esperaba un número, un parámetro fuera de rango, o un argumento obligatorio dejado en blanco. Revisa los tipos de parámetro de la función contra lo que realmente contienen las celdas referenciadas.

Un mensaje de error personalizado sigue mostrándose como un código estándar

Una función puede lanzar un error específico (valor inválido, división por cero, un nombre que no reconoce) y Excel siempre lo muestra como uno de sus propios códigos — el mensaje subyacente no se pierde, eso sí: pasa el ratón por el indicador de error de la celda, o revisa la ejecución de prueba de la función en el panel, para ver el texto real.

El agent no reconecta

"No replicas serving this environment yet" — el agent de este entorno nunca se ha conectado. Comprueba las variables de entorno en el host (CONNXL_BACKEND_URL, el token de inscripción o las variables de atestación) y que el host pueda alcanzar el backend hacia fuera.
"No replicas are currently reporting" — el agent se ha conectado antes pero no está conectado ahora mismo. Comprueba que el proceso realmente se esté ejecutando en el host, y que el acceso de red saliente hacia el backend no se haya bloqueado desde la última conexión con éxito.
Marcado offline tras ~10 minutos de silencio — un agent que deja de latir se marca como offline y levanta automáticamente una alerta agent_offline; se despeja en el momento en que el agent se reconecta. Consulta Alertas.
Una réplica concreta sigue reconectando y no quieres que lo haga — desde la lista de instancias de la página Agent, haz Evict de esa réplica. El evict la drena y bloquea su id de instancia para que no vuelva a conectarse con el certificado del entorno; Restore levanta el bloqueo si evictaste la equivocada.

Fallos de certificado / inscripción

La única credencial del agent es su certificado mTLS, obtenido una sola vez durante la inscripción. Los fallos aquí casi siempre son uno de estos:

"Enrollment token invalid or already used" — los tokens son de un solo uso y se consumen en el momento en que un agent se inscribe con éxito con ellos. Genera un token nuevo desde la página Agent del entorno (un token nuevo reemplaza a cualquier token sin usar que quedara pendiente) y ponlo antes de reiniciar.
Add-in o entorno equivocado — la ruta de inscripción por atestación en la nube (CONNXL_ENROLL_ATTESTATION) lee CONNXL_ADDIN_ID/CONNXL_ENV_ID directamente; un id equivocado inscribe contra el entorno equivocado (o falla directamente). Copia ambos desde la página Agent en la que te estás inscribiendo.
Atestación en la nube rechazada — la identidad en la nube de la instancia (cuenta/proyecto/suscripción, opcionalmente fijada a una región) no está en la lista blanca de Trusted cloud identities del entorno. Añade una regla en la pestaña Seguridad de la página Agent para el proveedor y la cuenta en la que realmente se ejecuta la instancia.
El panel de tareas / las funciones no cargan, pero el agent está corriendo — Office requiere HTTPS. En el modo edge por defecto el agent sirve HTTP plano en :3000 y depende de un balanceador que termina el TLS delante; exponlo directamente en HTTP y Excel rechaza el origen no confiable. En el modo CONNXL_TLS_TERMINATION=agent el agent necesita cert.pem/key.pem junto al binario para servir la superficie del complemento — sin ellos registra un aviso y no sirve nada a Excel (el enlace al backend, la telemetría y el heartbeat siguen funcionando). Este par cert.pem/key.pem es distinto del mTLS de arriba; consulta el aviso de abajo.
El agent arranca pero cada llamada al backend falla en la autenticación — comprueba que CONNXL_MTLS_CERT/CONNXL_MTLS_KEY realmente apunten a rutas donde se puede escribir y que no se hayan apuntado por error al cert.pem/key.pem de cara a Office.

Dos pares de certificado, dos trabajos distintos

cert.pem/key.pem junto al binario son para que Excel confíe en el propio endpoint HTTPS del agent — y solo aplican cuando CONNXL_TLS_TERMINATION=agent (en el modo edge por defecto ese certificado lo tiene el balanceador). CONNXL_MTLS_CERT/CONNXL_MTLS_KEY son dónde el agent guarda el certificado con el que se inscribe, para autenticarse ante el backend, siempre. Confundirlos es la queja de inscripción más común con diferencia — consulta Mutual TLS para el ciclo de vida completo.

Dónde mirar

Cuando las comprobaciones de arriba no lo explican, saca más señal directamente del agent:

Registros del proceso del agent — el panel de diagnóstico de la página Agent trae una cola en vivo del propio registro de proceso del agent (no analíticas — sus líneas internas de debug/info/error), que suele ser la forma más rápida de ver la excepción real detrás de una función que falla. Consulta Registros y exportaciones para ver en qué se diferencia de la página de Registros de uso/telemetría.
Run diagnostic — una autocomprobación del agent con un clic, desde el mismo panel; útil antes de abrir un ticket de soporte.
Report health — fuerza una instantánea nueva de CPU/memoria/disco en lugar de esperar a la siguiente programada.
La línea de tiempo de estado y el banner de alertas abiertas en la página Agent — para problemas de presión de recursos (CPU/memoria/disco acercándose al umbral de advertencia o crítico) en lugar de una función concreta que falla.

Registros y exportaciones

Analíticas de uso y el visor de registros del proceso del agent.

Versiones

El modelo de borrador/en vivo detrás del problema más común de "está en blanco".