Resolução de problemas

A minha fórmula está em branco

De longe a surpresa mais comum, e quase sempre com a mesma causa: ainda não publicaste. Editar uma ligação, função, botão de friso ou painel de tarefas só altera o rascunho de trabalho do ambiente — não chega ao Excel até publicares deliberadamente.

1. Abre a página Versions do ambiente e verifica o banner. Um banner âmbar de "alterações por publicar" significa que o rascunho e a versão ativa diferem.
2. Clica em Save version, mantém "Make this version live" marcado, e guarda.
3. Recalcula a pasta de trabalho. A fórmula deve agora resolver-se.

Se o banner estiver azul (nada por publicar) e a fórmula continuar em branco, confirma que a função existe mesmo no ambiente contra o qual estás a testar — os ambientes fora de produção sufixam o espaço de nomes (=NAMESPACE_DEV.MODULE.FN(…) para Development, _QA para QA, e assim por diante), por isso uma pasta de trabalho ligada ao espaço de nomes do ambiente errado nunca vai encontrar a função. Consulta Versões para o modelo rascunho/ativo completo.

Códigos de erro do Excel

Estes são valores de erro do próprio Excel, mostrados na célula — não é algo que o ConnXL inventa. Aqui está o que cada um significa quando vem de uma função ConnXL, e o que verificar.

O agent não volta a ligar-se

• "No replicas serving this environment yet" — o agent deste ambiente nunca se ligou. Verifica novamente as variáveis de ambiente no host (CONNXL_BACKEND_URL, o token de inscrição ou as variáveis de atestação) e se o host consegue alcançar o backend de saída.
• "No replicas are currently reporting" — o agent já se ligou antes mas não está agora. Verifica se o processo está mesmo a correr no host, e se o acesso de rede de saída para o backend não foi bloqueado desde a última ligação bem-sucedida.
• Marcado como offline ao fim de ~10 minutos de silêncio — um agent que para de enviar batimentos é marcado como offline e levanta automaticamente um alerta agent_offline; limpa-se no momento em que o agent volta a ligar-se. Consulta Alertas.
• Uma réplica específica continua a voltar a ligar-se e não a queres — a partir da lista de instâncias da página Agent, faz Evict a essa réplica. A expulsão drena-a e bloqueia o seu instance id de voltar a ligar-se com o certificado do ambiente; Restore levanta o bloqueio se expulsaste a errada.

Falhas de certificado / inscrição

A única credencial do agent é o seu certificado mTLS, obtido uma vez na inscrição. As falhas aqui são quase sempre uma destas:

• "Enrollment token invalid or already used" — os tokens são de uso único e consumidos no momento em que um agent se inscreve com sucesso com eles. Cria um token novo a partir da página Agent do ambiente (um token novo substitui qualquer token por usar que ainda esteja pendente) e define-o antes de reiniciar.
• Add-in ou ambiente errado — o caminho de inscrição por atestação de cloud (CONNXL_ENROLL_ATTESTATION) lê CONNXL_ADDIN_ID/CONNXL_ENV_ID diretamente; um id trocado inscreve-se no ambiente errado (ou falha por completo). Copia ambos a partir da página Agent em que te estás a inscrever.
• Atestação de cloud rejeitada — a identidade de cloud da instância (conta/projeto/subscrição, opcionalmente fixada a regiões) não está na lista de permissões Trusted cloud identities do ambiente. Adiciona uma regra no separador Security da página Agent para o fornecedor e a conta em que a instância corre de facto.
• O agent não arranca de todo, nenhuma tentativa de inscrição — o Office exige HTTPS, por isso o agent recusa-se a arrancar sem cert.pem/key.pem ao lado do binário. Este é um par de certificado diferente do mTLS acima; consulta a nota abaixo.
• O agent arranca mas todas as chamadas ao backend falham na autenticação — verifica se CONNXL_MTLS_CERT/CONNXL_MTLS_KEY apontam mesmo para caminhos com permissão de escrita e não foram apontados por engano para o cert.pem/key.pem voltado para o Office.

Onde procurar

Quando as verificações acima não explicam o problema, vai buscar mais sinal diretamente ao agent:

• Logs de processo do agent — o painel de diagnóstico da página Agent obtém uma cauda ao vivo do próprio log de processo do agent (não análises — as suas linhas internas de debug/info/error), normalmente a forma mais rápida de ver a exceção real por trás de uma função com falha. Consulta Logs e exportações para ver como difere da página Logs de utilização/telemetria.
• Run diagnostic — uma autoverificação do agent com um clique, no mesmo painel; útil antes de abrir um pedido de suporte.
• Report health — força um snapshot novo de CPU/memória/disco em vez de esperar pelo próximo agendado.
• A linha temporal de saúde e o banner de alertas em aberto na página Agent — para problemas de pressão de recursos (CPU/memória/disco a aproximar-se do limiar de aviso ou crítico) em vez de uma função específica a falhar.