Falhas de build

Quando o gerador estático falha, o site não fica fora do ar: seu build anterior continua servindo até você resolver o problema e reconstruir. Esta página explica onde as falhas de build são reportadas, o que os diferentes resultados significam e o que experimentar.

Onde olhar

Dois lugares dizem como foi o último build:

Dashboard: painel de status do build. Ele mostra o estado atual de forma direta: build em andamento, a hora do último build, Build Failed (com "Last build exited with an error: site may be out of sync. Check build history below."), ou Promotion blocked quando um build perdeu páginas demais (o motivo exato, vindo do próprio build, é exibido).
Histórico de builds. Os últimos 100 builds são guardados com sua saída completa: cada linha mostra OK, Error ou Blocked, o timestamp, o número de arquivos escritos (ou a mensagem de falha) e o log completo do build em uma seção expansível.
Uma URL de status no estilo /health também responde com a hora do último build e se um build está em andamento no momento, para monitores.

Os três resultados

Error: o gerador encontrou erros de renderização (por exemplo, um template quebrado) e se recusou a promover. A saída de staging é descartada e a saída anterior ao vivo permanece no lugar. A mensagem de falha lista os templates problemáticos, como "page.tt for 'about'" (os primeiros, depois a contagem do restante).
Blocked: o build terminou, mas o gerador o comparou com o último build bom e viu uma queda grande demais (mais de 80% das páginas perdidas) ou um pico de links quebrados ou problemas de acessibilidade, o que normalmente significa que o build estava quebrado mesmo tendo "tido sucesso". O build anterior continua servindo: conteúdo desatualizado, nunca conteúdo quebrado.
OK: tudo foi promovido; a linha mostra quantos arquivos foram escritos, além do log completo.

Primeiras coisas a experimentar

Rebuild completo. Um rebuild completo e limpo re-renderiza cada página do zero. Se um build incremental aparentemente perdeu suas alterações, isso limpa o cache de build e reconstrói do zero; o botão "Full rebuild" do dashboard faz isso (com uma confirmação; é mais lento que o padrão incremental). A variável de ambiente de emergência CHINASKI_FORCE_FULL=1 faz o mesmo a partir de um script de operações.
Promote anyway. Se um build foi bloqueado mas você tem certeza de que está correto, "Promote anyway" no dashboard o publica contornando a proteção apenas para aquele build. Essa é uma válvula de escape de uso único: ela não reinicializa as medidas com que a proteção compara, e deve continuar sendo um caminho incomum.
Verifique o health endpoint. É a forma mais rápida de ver se um problema de ambiente preexistente causou a falha: diretório de saída gravável, espaço livre em disco, arquivo do gerador presente, o motor de templates compila, e assim por diante.

O que geralmente causa uma falha de build

As fontes mais comuns de mensagens de falha são:

Erros de renderização de template: uma página ou bloco que falha ao renderizar. A mensagem nomeia os três primeiros templates problemáticos.
O ambiente de inicialização: executar o gerador como root (ele se recusa), arquivo de banco de dados ausente ou script de build ausente.
Tetos de recursos sendo atingidos. Um build é abortado quando tenta escrever mais que o orçamento de escrita de 2 GiB; cada build também tem um limite de 30 minutos de relógio, e depois disso o build é morto e a saída anterior continua servindo.
Assinatura do manifesto. Os builds assinam seu manifesto de arquivos, e um build verde sem manifesto assinado válido é tratado como falha: a promoção é abortada. Ambientes de teste podem desativar isso com um flag de ambiente.

Onde o log vive depois de resolvido

Após uma falha, as linhas expansíveis do histórico de builds são sua melhor ferramenta: a saída completa do build que falhou está lá para colar em um ticket de suporte, além das contagens dos templates problemáticos para estreitar o problema.

Contagens de motivos e seus efeitos

Um build chega à etapa de promoção apenas quando não há erros de renderização. Qualquer erro de renderização (mesmo um só) bloqueia a promoção imediatamente.
Erros fatais (no início do build) mantêm o site ao vivo funcionando porque o build anterior não é substituído após uma falha.