# Solução de problemas

> Correções sintoma por sintoma: jobs travados em fila, um painel vazio, insights ausentes, login bloqueado e mais.

Source: https://latchkey.dev/pt/documentation/troubleshooting

## Summary

- Um job travado em **fila** = label, monitoramento, configuração, cobrança, build de imagem ou concorrência; verifique nessa ordem.
- Um painel vazio quase sempre é questão de filtros ou tempo de backfill, não de dados perdidos.
- Todo estado bloqueado tem um indicador explícito: um banner, o sino de notificações ou o selo no modal de Cobrança.

Cada seção abaixo é um sintoma, com suas causas na ordem em que mais vale a pena verificá-las. A maioria dos problemas se anuncia em algum lugar: um banner no painel, uma notificação no sino ou um status em um modal. Esta tabela indica onde olhar primeiro.

| Sintoma | Primeira verificação | Onde |
| --- | --- | --- |
| Job direcionado a um runner permanece em fila | A string exata do label | A tabela "Your runners" na página Latchkey Runners |
| O painel não mostra dados | Um repositório está selecionado | A barra de filtros no topo de toda página de análise |
| Sem insights de IA | O banner de processamento e a branch de análise | A página de Insights e o modal de Monitoramento |
| Lançamentos de runner bloqueados | Estado de trial, assinatura e camada gratuita | O modal de Cobrança e a notificação "Managed runner blocked" |
| Acesso subitamente bloqueado | Status da assinatura (trial encerrado, Past Due, Canceled) | A tela de ativação ou o modal de Cobrança |

## Um job direcionado a um runner Latchkey permanece em fila

Este é o sintoma universal para qualquer coisa que impeça o provisionamento de um runner. O GitHub mantém um job em "fila" até que um runner com um label correspondente o pegue, e quando o Latchkey bloqueia ou não consegue rotear um lançamento não há erro do lado do GitHub; o job simplesmente aguarda. Isso significa que o diagnóstico sempre acontece do lado do Latchkey. Para saber como o provisionamento decide entre uma captação a quente e um início a frio quando nada está errado, veja [Como funciona o provisionamento](/documentation/runner-provisioning). Faça a triagem nesta ordem:

1. **Descarte um erro de digitação no label** O label deve ser exatamente `latchkey-small`, `latchkey-medium`, `latchkey-large`, `latchkey-xlarge` ou um dos seus labels personalizados. **Como confirmar:** a tabela "Your runners" na página Latchkey Runners mostra as strings exatas; compare com seu arquivo de workflow caractere por caractere (um espaço perdido ou um hífen errado já basta para não corresponder). Ambas as formas de label roteiam de forma idêntica, então `runs-on: latchkey-small` e `runs-on: [self-hosted, latchkey-small]` se comportam da mesma maneira; a forma de array não é o problema.
2. **Confirme que o repositório está monitorado** Runners gerenciados só atendem repositórios monitorados, então um job de um repo não monitorado aguarda para sempre. **Como confirmar:** abra o modal de Monitoramento na barra lateral do painel (donos e admins) e verifique o toggle do repositório. Se você estiver no limite de repositórios do seu plano, novos toggles são bloqueados e o modal aponta para o upgrade; veja [Gerenciando repositórios](/documentation/managing-repositories).
3. **Verifique se a configuração do runner está habilitada** Uma configuração desabilitada para de aceitar novos jobs, e jobs direcionados ao seu label ficam em fila. **Como confirmar:** a linha da configuração na [página de Runners](/documentation/runners-dashboard) mostra seu estado de habilitado/desabilitado, tanto para os presets quanto para runners personalizados.
4. **Verifique o estado de trial, assinatura e camada gratuita** Um trial expirado, uma assinatura vencida (past due ou cancelada) ou uma camada gratuita esgotada em um trial sem cartão bloqueiam todos os novos lançamentos de runner. **Como confirmar:** procure por uma notificação "Managed runner blocked" no sino de notificações, depois abra o modal de Cobrança: o selo de status (Trial, Active, Past Due, Canceled) e o medidor de camada gratuita indicam em qual caso você está. Assinar, ou corrigir o método de pagamento no portal do Stripe, restaura os lançamentos imediatamente; veja [Uso de runners e minutos gratuitos](/documentation/runner-usage-and-free-minutes).
5. **Verifique se uma imagem personalizada ainda está sendo construída** Jobs direcionados a uma nova configuração personalizada aguardam até que sua imagem termine de ser construída. **Como confirmar:** a linha da configuração na página de Runners mostra o status do build da imagem, e você é notificado quando o runner está pronto ("AI scan runner is ready") ou se o build falhou. Veja [Runners personalizados](/documentation/custom-runners).
6. **Verifique o teto de concorrência** Se 20 jobs já estão em execução (o limite padrão por workspace; runners quentes ociosos não contam), jobs adicionais aguardam por uma vaga. **Como confirmar:** isso aparece quando muitos workflows disparam ao mesmo tempo em seus repositórios, e os jobs em fila iniciam por conta própria à medida que os jobs em execução terminam. Limites mais altos estão disponíveis; veja [Limites e concorrência](/documentation/runner-limits).

> ****
> Um job travado cancela com segurança pela interface do GitHub. Depois de corrigir a causa, execute-o novamente; nada do estado da fila permanece.

## O painel não mostra dados

Um painel vazio quase sempre significa filtros ou tempo, não dados perdidos. Verifique nesta ordem:

1. **Nenhum repositório selecionado.** A barra de filtros orienta toda página de análise, e as páginas solicitam que você escolha um repositório se nada estiver selecionado. **Como confirmar:** verifique o seletor de Repositório na barra de filtros no topo; se os filtros estiverem em um estado confuso, **Reset filters** os retorna aos padrões.
2. **Backfill ainda em execução.** Um repositório recém-habilitado importa o histórico recente primeiro, e a maioria das equipes vê dados em poucos minutos. **Como confirmar:** o banner de progresso do backfill aparece no painel até que a importação seja concluída; aguarde ele desaparecer antes de avaliar as páginas.
3. **Nenhuma execução na janela.** O backfill cobre execuções concluídas dos últimos 30 dias, e o filtro de intervalo de datas deve se sobrepor à atividade real. **Como confirmar:** verifique as execuções de workflow recentes do repositório no GitHub; se a última execução for anterior à janela de backfill, as páginas permanecem vazias até que novas execuções ocorram. Amplie o seletor de intervalo de datas antes de concluir que há dados faltando.
4. **App instalado na org errada.** Se o GitHub App não estiver instalado na organização que possui os repositórios, nenhum evento chega. **Como confirmar:** no GitHub, abra as Settings da organização, depois GitHub Apps, e verifique se o Latchkey está listado lá. Corrija instalando na organização correta; veja [Instale o GitHub App](/documentation/install-the-github-app).

## Nenhum insight de IA está aparecendo

A geração de insights é automática e orientada a eventos; não há botão para apertar. O agente é executado após o backfill inicial de um repositório recém-monitorado, quando um arquivo de workflow muda na branch de análise, em falhas consecutivas repetidas, em um pico de custo e em degradação de desempenho. Então "sem insights" geralmente significa que o gatilho ainda não disparou, ou que o agente está olhando para uma branch diferente da sua:

- **Análise ainda em execução ou ainda não disparada.** Insights são gerados automaticamente após o backfill ser concluído. **Como confirmar:** a página de Insights mostra um banner de processamento enquanto o agente é executado; dê a um novo repositório alguns minutos.
- **Branch de análise errada.** A análise segue a **branch de análise** escolhida no modal de Monitoramento (a branch padrão do repositório por padrão); workflows que existem apenas em outras branches não são analisados. **Como confirmar:** abra o modal de Monitoramento e verifique o seletor de branch ao lado do repositório. Veja [Gerenciando repositórios](/documentation/managing-repositories).
- **Legitimamente pouco a dizer.** Workflows pequenos ou raramente executados podem produzir poucas recomendações; isso é um achado, não uma falha. Editar um arquivo de workflow reaciona a análise, então volte a verificar após a sua próxima mudança de workflow.

## Aplicar recomendações falhou ou descartou mudanças

As recomendações são geradas com base no arquivo de workflow como ele existia no momento da análise. Se o arquivo mudou desde então (suas edições, ou um PR do Latchkey anteriormente mesclado), algumas recomendações deixam de se aplicar de forma limpa:

- O Latchkey abre o PR com o que ainda se encaixa e lista as recomendações que precisam de colocação manual. O PR chega com o título "Latchkey insight: <what it does>" (por exemplo "Latchkey insight: pin GitHub Actions to commit SHAs") em uma branch `latchkey/insight-<detector>-<hex>`, e um banner de sucesso leva você diretamente a ele.
- Se todas as recomendações selecionadas foram descartadas, não tente novamente o conjunto desatualizado. Editar o workflow dispara uma nova análise; aguarde ela terminar (o banner de processamento na página de Insights desaparece), então aplique a partir do conjunto novo. Veja [Insights de otimização](/documentation/optimization-insights).

## Um pagamento falhou e o acesso está bloqueado

Um status **Past Due** significa que um pagamento falhou: o acesso ao painel e à API é bloqueado e os lançamentos de runner param até que o método de pagamento seja corrigido no portal do Stripe, onde métodos de pagamento, faturas (com PDFs) e detalhes da assinatura são gerenciados. Se a assinatura foi **Canceled** em vez disso, o acesso é bloqueado mas a cobrança permanece acessível para que você possa reassinar. Seus dados são retidos em ambos os casos. Os status e seus efeitos estão listados em [Gerenciando sua assinatura](/documentation/managing-billing).

## Não consigo usar o painel no meu celular

Isso é intencional por enquanto: o painel é apenas para desktop, e navegadores de celular e tablet veem um aviso de bloqueio após o login. [Notificações](/documentation/notifications) por email, Slack e push, além do resumo semanal, mantêm você informado longe da sua mesa.

## Instalei o app na minha conta pessoal

Contas pessoais não são suportadas. O Latchkey removeu automaticamente essa instalação, então não há nada para limpar; refaça o onboarding e escolha uma **organização** do GitHub. Se você só tem uma conta pessoal, crie uma organização primeiro (gratuito no GitHub) e mova seus repositórios para ela. Detalhes em [Instale o GitHub App](/documentation/install-the-github-app).

## Meu trial encerrou e está tudo bloqueado

Seus dados estão intactos; o bloqueio é no acesso, não no armazenamento. O painel é substituído por uma tela "Your free trial has ended", o acesso à API é bloqueado com a mesma mensagem, e os lançamentos de runner gerenciado são bloqueados (jobs direcionados a labels `latchkey-*` permanecem em fila no GitHub em vez de dar erro). Assine a partir da tela de ativação (ou do modal de Cobrança, se você conseguir alcançá-lo) e o acesso, incluindo os lançamentos de runner, é restaurado imediatamente. O trial roda uma vez por workspace, então assinar ou mudar de plano não o reinicia. Veja [Planos e o trial gratuito](/documentation/plans-and-trial).

## Ainda travado?

O [FAQ](/documentation/faq) cobre as respostas rápidas. Para qualquer outra coisa, vá para o [Suporte](/support) ou use **Send Feedback** na barra lateral do painel; ambos chegam diretamente à equipe.

### Meu job está preso em queued. O que verifico primeiro?

Seis coisas, nesta ordem: o label do runner, se o repositório está monitorado, a configuração do runner, o estado da cobrança, um build de imagem ainda em andamento e o teto de concorrência. Cada um tem um sinal explícito, então percorrer a lista encontra a causa mais rápido do que adivinhar.

### Meu painel está vazio. Para onde foram meus dados?

Quase sempre é a barra de filtros ou o tempo da importação, e não dados perdidos. Amplie o intervalo de datas e limpe os filtros de repositório e workflow primeiro; se o workspace é novo, a importação dos últimos 30 dias pode ainda estar em andamento.

### Instalei o GitHub App na minha conta pessoal. E agora?

O Latchkey exige uma organização, então uma instalação pessoal não pode ser usada. Crie uma organização gratuita, transfira o repositório para ela e instale o app lá; o teste e os dados coletados acompanham o workspace, não a instalação que falhou.

---

Latchkey runs CI/CD that repairs its own failures. Agent entry points: https://latchkey.dev/agent.txt, https://latchkey.dev/openapi.json, https://latchkey.dev/llms.txt