---
title: "Resolução de problemas"
description: "Modos de falha do TrustBridge por onde são percebidos, como cada um se manifesta e onde ler a causa, usando o X-Correlation-Id de cada resposta."
canonical: "https://docs.lacunasoftware.com/articles/trustbridge/troubleshooting"
locale: "pt-BR"
product: "TrustBridge"
last_updated: "2026-10-12"
---

# Resolução de problemas

Os modos de falha, organizados por onde são percebidos, como cada um se manifesta e onde ler a causa.
Toda resposta HTTP traz um `X-Correlation-Id`; informe-o e o operador encontra na hora as linhas do log
do Servidor e as linhas da Trilha de Auditoria da requisição.

## O Servidor não inicia

Toda inicialização recusada gera uma linha `Critical` citando a causa. A tabela completa está em
[Instalação do Servidor](https://docs.lacunasoftware.com/articles/trustbridge/server-installation#quando-o-servidor-não-inicia). A versão resumida:

| Sintoma | Causa |
|---|---|
| Uma linha citando `KeyRingProtector:` | Não há protetor, o valor não está em base64, a senha está errada ou não há chave RSA. Toda implantação precisa de um. |
| `…the Key Ring Protector configured here opens none of them` | Um protetor trocado. Restaure o antigo, ou adicione-o em `RetiredCertificates`. |
| `…could not be reached in 90 seconds` | O banco de dados nunca respondeu na inicialização. No Azure SQL, verifique o acesso pela rede pública ou o private endpoint (erro 47073). |
| `…is behind the build … by N migration(s)` | `MigrateOnStart` está desligado e há migrações pendentes. |
| `…has N migration(s) applied that this build does not contain` | Uma imagem mais antiga sobre um esquema mais novo, ou um banco de dados criado pelo Servidor 1.2.0 ou anterior. |
| `Signer:ApiKey is required…` | Um endereço do Signer sem chave. |
| `Sessions:MaxDuration` abaixo de `DefaultDuration`, ou outra regra entre chaves | Uma configuração recusada; a linha cita as duas chaves. |
| No App Service, o container é encerrado e reiniciado em loop sem nada útil no log | Uma migração que demora mais que `WEBSITES_CONTAINER_START_TIME_LIMIT` (padrão de 230 s). Defina-o como 1800. |

## O Servidor iniciou, mas não funciona

| Sintoma | O que é | Onde olhar |
|---|---|---|
| `/` responde 200, `/healthz` responde 503 | O banco de dados caiu depois da inicialização. O contrato falha; o cofre está fechado. | A connection string, a disponibilidade do SQL Server. |
| Toda assinatura e importação no cofre é recusada, enquanto as estações de trabalho assinam normalmente | A trava do cofre: o Servidor subiu antes do banco de dados. | O aviso `VaultReadiness` na inicialização. O cofre se abre no primeiro uso depois que o banco de dados responde. |
| Todo Certificado do Cofre aparece como `UNTRUSTED`; importações recusadas | Não há licença do PKI SDK, ou ela expirou. | A linha `Critical` de `LacunaPkiRuntime` na inicialização. Defina `Certificates__Validation__License`. |
| Todo certificado no Servidor aparece como `UNTRUSTED`, embora a licença esteja válida | Nenhuma âncora consegue terminar uma cadeia: `UseIcpBrasil` desligado sem nenhuma Autoridade Certificadora Confiável que seja raiz, ou um sistema de arquivos somente leitura sem `/tmp` gravável, de modo que a licença não pôde ser carregada. | As duas linhas `Critical` sobre o conjunto de âncoras; monte um `tmpfs` sobre `/tmp`. |
| Uma configuração não tem efeito | Uma das sete chaves que podem ser sobrepostas foi salva na tela **Configurações e usuários**, e a camada do banco de dados prevalece silenciosamente. | `/admin/settings`; restaure os padrões implantados. |
| O console administrativo em `http://` nunca conclui o login | Um cookie sem `Secure` em um link que a plataforma converte para HTTPS. | No App Service, `--https-only true`. Atrás de um proxy, `ASPNETCORE_FORWARDEDHEADERS_ENABLED=true`. |
| Toda linha de auditoria registra o endereço do proxy | Os forwarded headers estão desligados. | `ASPNETCORE_FORWARDEDHEADERS_ENABLED=true`. |
| Linhas `KeyRingProvider[48]` ou `XmlKeyManager[24]` em um Servidor que iniciou sem erros | O **banco de dados** está inacessível, não o protetor. | `/healthz`. |
| Uma linha `Critical` com uma linha de auditoria inteira | O banco de dados recusou uma gravação de auditoria; a linha só existe nessa entrada do log. | Guarde o fluxo de log. O console mostra um alerta. |
| Um banner de aviso em todas as páginas administrativas | `UseLacunaTestPki` está ligado, ou uma gravação de auditoria falhou. | Desligue a PKI de testes em tudo que não seja uma máquina de desenvolvimento. |

## Estações de trabalho

| Sintoma | O que é | Onde olhar |
|---|---|---|
| Instalação com código de saída 1603, log cita `SERVER_URL` | A condição de inicialização: URL vazia ou sem esquema. | Passe `SERVER_URL=https://…`. |
| Instalação com código de saída 1603, log diz que uma versão mais nova está instalada | Um downgrade. | Desinstale antes; a máquina volta como uma máquina nova. |
| A instalação é revertida em *Starting services* | O serviço se recusou a iniciar: uma licença que o SDK não lê, uma `INSTALLER_KEY` que não pode ser interpretada ou um valor de Registro do tipo errado. | Log de eventos Aplicativo, origem **TrustBridge Workstation Service**. |
| Instalada, nunca aparece na fila de admissão, nada no Servidor | A URL do Servidor está errada, ou uma GPO a está sobrepondo, ou a máquina não confia na cadeia TLS. | A linha *`Server:Url` is …, supplied by …* do serviço na inicialização; `HKLM\Software\Policies\TrustBridge` em um PowerShell de 64 bits. |
| Nunca aparece, e o log da máquina diz que a requisição de admissão foi recusada | Uma de quatro causas: revogada, uma Installer Key em que o Servidor não confia, requisições demais do endereço dela ou fila cheia. O Servidor deliberadamente não diz qual. | As duas últimas se resolvem sozinhas. Procure uma linha revogada na tela **Estações de Trabalho**. |
| Está na fila, e o Tray mostra *Ainda não admitida* | Não é uma falha. | Admita-a em `/admin/admission`. |
| Admitida, mas não se conecta; o log do Servidor diz `Protocol version 2 is newer than this server's supported window` | A estação de trabalho foi atualizada antes do Servidor. | Atualize o Servidor. |
| Admitida, mas não se conecta; o log do Servidor diz `A workstation assertion was refused: Expired` ou `NotYetValid` | O relógio da máquina está mais de 60 s fora. | A sincronização de horário da máquina. |
| Todo certificado aparece como `UNTRUSTED` | Não há licença da PKI, ou ela expirou, ou nenhuma âncora consegue terminar uma cadeia. | A linha `Critical` na inicialização do serviço; `PKI_LICENSE` por reparo ou por Diretiva de Grupo e, em seguida, reinicie o serviço. |
| Um certificado aparece como `UNTRUSTED` enquanto a licença está em ordem | O emissor dele não está no conjunto de âncoras da máquina. | **Confiar no emissor**, no Registro de Certificados, que adiciona uma Autoridade Certificadora Confiável que chega à máquina. Uma máquina no protocolo 1 precisa de arquivos de âncora. |
| Um certificado aparece como `STALE` | Não foi possível baixar a LCR da AC dele por mais tempo que a janela de tolerância (24 h). | Se a máquina consegue acessar a AC. |
| Um token está conectado, mas nenhum certificado aparece | Um middleware incomum, fora da lista fornecida; ou um módulo citado em `Certificates:Pkcs11:Modules` que não carrega. | O log do serviço cita o módulo. A varredura também detecta, em até um minuto, um gatilho de mudança perdido. |
| O Tray App não aparece depois da instalação | Ele inicia no próximo login. | Saia e entre de novo, ou inicie `Tray App\TrustBridge.TrayApp.exe`. |
| O Tray App diz *Sem conexão* | Ele não conseguiu abrir o pipe do serviço. O Workstation 1.0.0 tinha um bug aqui, corrigido na 1.0.1. | Atualize o pacote da estação de trabalho. |
| Uma solicitação de PIN continua na tela depois de o cliente já ter recebido um erro | Esperado: o timeout da solicitação no Servidor (60 s) é menor que o do Tray (90 s), e um Servidor que desistiu não consegue fechar a solicitação. | Nada. |
| Uma alteração de diretiva não teve efeito | O Registro é lido uma vez, na inicialização. | `Restart-Service "TrustBridge Workstation Service"`. |
| Uma máquina perfeitamente configurada parece vazia no Registro | Um PowerShell de 32 bits redirecionado para `WOW6432Node`. | Use um PowerShell de 64 bits. |
| Todo certificado de uma máquina aparece como `ACTIVE`, inclusive os de exemplo | `UseLacunaTestPki` ligado, ou uma seção `FakeTokens` no arquivo de configuração. | Remova os dois de qualquer máquina em que alguém assine. |

## Erros na aplicação cliente

Decida com base em `error.code`. O vocabulário completo está na página
[API REST](https://docs.lacunasoftware.com/articles/trustbridge/rest-api#o-envelope-de-erro).

| Código | Causa comum | O que fazer |
|---|---|---|
| `401 UNAUTHORIZED` | Chave ausente, digitada errado, revogada ou expirada, ou uma aplicação desativada. Todas recusadas da mesma forma. | Verifique a chave na tela **Aplicações Cliente**. |
| `401 SESSION_EXPIRED` | A sessão expirou por inatividade, foi desativada, foi substituída por uma mais nova do mesmo CPF, esgotou a Franquia de Assinaturas ou estava vinculada ao cofre durante um reinício do Servidor. | Crie uma nova sessão. Nada indica qual foi o caso; isso é deliberado. |
| `400 INVALID_REQUEST` em `POST /v1/sessions` citando `cpf` | Os dígitos verificadores não conferem, ou é um valor de dígitos repetidos. | Corrija o CPF na origem. Valide os dígitos verificadores no seu formulário. |
| `400 INVALID_REQUEST` em uma assinatura | Não há `sessionId` na requisição. | Envie o id que `POST /v1/sessions` retornou. Repetir sem alterações falha da mesma forma. |
| `404 CERT_NOT_FOUND` | Nenhum certificado do CPF está disponível em lugar nenhum: o token não está conectado, a máquina não está admitida ou conectada, ou o CPF nunca recebeu um certificado. | O Registro de Certificados e a tela **Estações de Trabalho**. |
| `422 CERT_NOT_ACTIVE` | Todo certificado do CPF está `EXPIRED`, `REVOKED`, `UNTRUSTED` ou `STALE`. `UNTRUSTED` muitas vezes significa que as âncoras da implantação não cobrem o emissor. | `GET /v1/certificates/info` para ver o veredito; o Registro de Certificados para ver o emissor. |
| `401 INVALID_PIN` | PIN errado, ou uma estação de trabalho com outro PIN em uso. | Pergunte ao titular. Cinco falhas em quinze minutos bloqueiam o CPF. |
| `422 PIN_NOT_AVAILABLE` | A solicitação no Tray expirou, foi recusada ou não havia ninguém conectado para respondê-la; ou um Certificado do Cofre não pôde ser aberto. | O titular precisa estar na máquina dele com o Tray App em execução. |
| `422 WORKSTATION_OFFLINE` | Toda máquina com um certificado ativo do CPF está offline, depois da tolerância de reconexão, em uma assinatura. | A tela **Estações de Trabalho**. |
| `422 CERT_INCOMPLETE_IDENTITY` | O certificado não traz endereço de e-mail. | Envie `email` ao criar a sessão. |
| `422 SIGN_TIMEOUT` | A assinatura não terminou dentro de `Signing:RequestBudget` (60 s). Uma máquina lenta ou um Signer lento. | A tela **Operações de Assinatura** mostra a etapa alcançada. |
| `422 SIGNER_REJECTED` | O Lacuna Signer recusou o documento; `details` traz a mensagem dele. | O próprio documento. |
| `502 SIGNER_ERROR` | Não foi possível acessar o Signer. | A disponibilidade do Signer, `Signer:BaseAddress`. |
| `409 DOCUMENT_NOT_READY` que nunca se resolve | A assinatura ainda está em andamento, ou uma execução foi interrompida por um reinício e o Signer ainda mantém o documento aberto. | A tela **Operações de Assinatura**; `RUN_STRANDED`. |
| `429 SERVER_BUSY` no uso normal | `Throttle:ConcurrencyLimit` baixo demais para a implantação; não é um problema do cliente. | Aumente-o. Em um pico real, tente de novo com backoff e jitter. |
| `429 TOO_MANY_PIN_ATTEMPTS` | O bloqueio por CPF. | Espere a janela (15 min) passar. Tentar de novo piora a situação. |
| `404 ENDPOINT_NOT_FOUND` | Uma rota sem o prefixo `/v1`. | Corrija a URL. |
| `413 DOCUMENT_TOO_LARGE` | Acima de `Signing:MaxDocumentBytes` (10 MB por padrão). | Um documento menor, ou aumente o limite sabendo o que isso custa. |
| `500 INTERNAL_ERROR` em uma assinatura, com `could not be opened by the reader this platform signs with` no log do Servidor | Um Certificado do Cofre importado antes de existir a verificação do formato legado, protegido com `pkcs5PBES2`. | Exporte de novo com `openssl pkcs12 -export -legacy` e importe outra vez. Isso exige o arquivo original. |

## Resultados de assinatura na tela Operações de Assinatura

Uma operação **Com falha** traz um código de falha e a **etapa** que alcançou: o `202` do cliente pode ter
sido respondido muito antes. `RUN_STRANDED` significa que o Servidor foi reiniciado durante a execução
e uma varredura a encerrou. Uma execução que falhou depois de o documento chegar ao Signer deixa um
documento aberto lá, que a busca informa como `409` até que a retenção do próprio Signer ou a limpeza
o encerre como `422`.

## Como obter ajuda

Envie ao suporte da Lacuna Software o `X-Correlation-Id` da requisição que falhou, a versão do
Servidor exibida no rodapé do console administrativo, a versão do pacote da estação de trabalho
mostrada na tela **Estações de Trabalho** e as linhas relevantes do log do Servidor. Para um problema
em uma estação de trabalho, acrescente as entradas do log de eventos Aplicativo com origem
**TrustBridge Workstation Service**. Nunca envie um PIN, uma chave de API, o Protetor do Chaveiro nem
a licença.