Skip to content

Solução de problemas ​

Primeiro diagnóstico ​

Quando um comando falha:

  1. Leia o código do erro e os próximos passos impressos pela CLI. Cada categoria de erro tem uma página em Erros da CLI.

  2. Rode o diagnóstico do alvo:

    bash
    CLOUD=aws ENVIRONMENT=sandbox  # ou: azure, prod
    finnest doctor --cloud="$CLOUD" --environment="$ENVIRONMENT"
  3. Se a falha foi num deploy, peça o diagnóstico da execução:

    bash
    CLOUD=aws ENVIRONMENT=sandbox  # ou: azure, prod
    finnest recover deploy --run=latest --cloud="$CLOUD" --environment="$ENVIRONMENT"

    O comando só lê as evidências. Ele indica em que etapa o deploy parou e qual o próximo comando seguro. Veja Recuperação de deploy.

  4. Para acionar o suporte, gere o pacote de suporte e envie-o com o código do erro:

    bash
    finnest support bundle --run=<id-da-execução>

Evidências de execução ​

Cada comando grava uma evidência redigida em .finnest/runs/<comando>/<execução>/, no diretório onde foi executado:

ArquivoConteúdo
envelope.jsonResultado final: status, código de saída, alvo, resumo das etapas, erro e próximos passos.
events.ndjsonEventos do comando, em ordem.
run.json e deploy-events.ndjsonNo deploy: resumo da execução e eventos de cada etapa.
raw/pulumi-bootstrap.logSaída da preparação do estado da infraestrutura.
raw/pulumi-deploy.logSaída da criação da infraestrutura e do runtime.
raw/pulumi-destroy.logSaída do destroy.

Para listar e abrir execuções anteriores:

bash
finnest runs
finnest runs show <execução>

Por alvo, a CLI mantém as 25 execuções mais recentes, até 200 MiB. Mude esses limites na seção [runs] do finnest.toml, com keep (quantidade) e max_bytes (em bytes). Execuções que falharam nunca são apagadas.

Arquivos de configuração legados ​

Instalações antigas podiam apontar a CLI para arquivos de configuração do runtime, na seção [runtime] do finnest.toml (bootstrap_config, deploy_config) ou nas variáveis RUNTIME_CD_*_CONFIG_PATH. A CLI atual não precisa desses arquivos.

Configuração de bootstrap ​

Erros: BOOTSTRAP_CONFIG_FILE_MISSING, BOOTSTRAP_CONFIG_PLACEHOLDERS, CONFIG_FILE_UNREADABLE.

O arquivo de bootstrap configurado não existe, não pode ser lido ou ainda tem valores __FINNEST_REQUIRED_… do modelo.

Configuração de deploy ​

Erros: DEPLOY_CONFIG_FILE_MISSING, DEPLOY_CONFIG_PLACEHOLDERS, CONFIG_FILE_UNREADABLE.

O arquivo de deploy configurado não existe, não pode ser lido ou ainda tem valores do modelo.

Configuração de destroy ​

Erros: DESTROY_CONFIG_FILE_MISSING, DESTROY_CONFIG_PLACEHOLDERS, CONFIG_FILE_UNREADABLE.

O arquivo usado pelo destroy não existe, não pode ser lido ou ainda tem valores do modelo.

Como corrigir ​

  1. Remova a referência ao arquivo legado do finnest.toml (ou a variável RUNTIME_CD_*_CONFIG_PATH). Se o suporte Finnest pediu para manter o arquivo, restaure-o e preencha os valores pendentes.

  2. Atualize os metadados da estação:

    bash
    finnest setup
  3. Repita o comando que falhou.

Situações comuns ​

O deploy pede --yes ​

Todo --apply altera a nuvem e exige confirmação explícita:

bash
CLOUD=aws ENVIRONMENT=sandbox  # ou: azure, prod
finnest deploy --cloud="$CLOUD" --environment="$ENVIRONMENT" --apply --yes

O sandbox não responde ​

O sandbox pode estar pausado para economizar custo:

  • Na Azure, nos modos de custo economy e standard, o cluster desliga fora do horário comercial, a menos que off_hours_stop diga o contrário.
  • Na AWS, o sandbox pausa sozinho depois de duas horas sem atividade, quando a pausa automática está ativa; a verificação power-automation do finnest doctor avisa quando ela está desligada. O desligamento fora do horário só vale com off_hours_stop = "true".

Para religar:

bash
CLOUD=aws  # ou: azure
finnest resume --cloud="$CLOUD" --environment=sandbox --yes

A sessão da nuvem expirou ​

Renove o login (AWS SSO ou az login) e rode finnest doctor de novo antes de repetir o deploy.

Falha nos testes de fumaça depois do deploy ​

Se o deploy parou na etapa smoke, a infraestrutura já está no ar. Corrija a causa apontada (normalmente certificado, credencial ou configuração regulatória) e rode só os testes:

bash
CLOUD=aws ENVIRONMENT=sandbox  # ou: azure, prod
finnest smoke --cloud="$CLOUD" --environment="$ENVIRONMENT"

Envio real do PCM do Open Finance (pcm_live) ​

pcm_live = true liga o envio real ao PCM do Open Finance no próximo finnest deploy. A chave vale por alvo, num alvo nomeado ou na forma legada de alvo único:

toml
[profile.<id>]
pcm_live = true

# Forma legada:
[deployment.pcm]
live = true

Ela chega ao runtime como runtime:pcm.live na AWS e na Azure e leva as três credenciais do PCM para o segredo pcm-banking-credentials do serviço de banking. Sem a chave, ou com false, o envio real fica desligado.

O deploy grava essas credenciais no cofre de segredos da nuvem a partir do ambiente da execução do finnest deploy, a única origem que a CLI lê para elas (não são material regulado, então o finnest secrets write não as aceita). Com o envio real ligado, defina as três em todo deploy:

bash
export FINNEST_PCM_SS_CLIENT_ID=<client id do software statement do PCM>
export FINNEST_PCM_TRANSPORT_CERT_PEM="$(cat <arquivo PEM do certificado de transporte do PCM>)"
export FINNEST_PCM_TRANSPORT_KEY_PEM="$(cat <arquivo PEM da chave de transporte do PCM>)"

Todo relatório identifica a participante pela organização dela no Diretório do OFB, que não é segredo: declare ofb_org_id em [opin] no finnest.toml. Ele chega ao runtime como runtime:ofb.organisationId, sua única origem.

toml
[opin]
ofb_org_id = "<UUID da organização no Diretório do OFB>"

Numa instalação gerida pelo configuration workspace, toda edição à mão dessas chaves pede um novo commit do workspace antes do deploy. A instalação é gerida pelo workspace quando já há um commit dele, ou quando o alvo tem um material_set: o de [profile.<alvo>] ou, se o alvo não declara um, o de [opin]. Sem ele, o finnest doctor aponta a falta (workspace-receipt) e o deploy recusa com RUNTIME_WORKSPACE_RECEIPT_INVALID:

bash
finnest config workspace open --goal=apply --json
finnest config workspace review <workspace> <revisão>
finnest config workspace commit <workspace> <revisão> review

Use a revisão que cada resposta devolve.

Com pcm_live = true e alguma credencial ausente, ou sem ofb_org_id, a verificação ofb-pcm-live-credentials da preparação do deploy para o finnest deploy (preview e apply) com DEPLOY_PREFLIGHT_FAILED antes de qualquer alteração, nomeando o que falta. O finnest doctor mostra a mesma falta como aviso. O finnest deploy --preview mostra o plano de recursos e a contagem de mudanças das pilhas de plataforma e de runtime, não uma comparação dos valores de configuração do runtime: confira a chave em finnest config show antes de aplicar.

Encerrar a sessão de um consentimento OFB revogado ​

Uma implantação que serve a jornada de autorização OFB encerra a sessão do Keycloak de cada consentimento que deixa AUTHORISED. Declare em [opin] no finnest.toml:

toml
[opin]
ofb_session_revocation = true

O flag liga juntos o event runtime e o relay de eventos do banking. Gere uma vez o segredo da conta de serviço com finnest secrets write ofb-session-revoker-client-secret; finnest doctor indica esse comando enquanto ele faltar. O papel manage-users dessa conta alcança todos os usuários do realm OFB, e é o papel mais estreito que o Keycloak oferece para apagar uma sessão: só o worker de revogação e o bootstrap do Keycloak leem o segredo.

O relatório PCM do OPIN não chega ao PCM ​

A participante receptora reporta ao PCM (Plataforma de Coleta de Métricas) cada chamada feita a uma transmissora. Comece pelo estado:

bash
finnest opin pcm status
  • Real sending OFF (FINNEST_OPIN_PCM_LIVE=off) quer dizer que o envio real está desligado no serviço de seguros: os relatórios são montados e assinados, mas nada chega ao PCM. Em produção, o relatório regulatório não está sendo entregue. Enquanto isso, opin pcm approve responde OPIN_PCM_REAL_SENDING_OFF.
  • As pendências listam cada relatório que o PCM descartou ou que o serviço recusou antes do envio, com a mensagem literal, o correlationId, o endpoint e o status HTTP. A exceção é um Duplicated register que volta depois de um POST que ficou sem resposta: o PCM já tem esse relatório, então ele conta como entregue e não aparece nas pendências. O correlationId é o id do registro na trilha, não o id da chamada. Nas pendências de chamadas, o x-fapi-interaction-id aparece no campo interactionId de finnest opin pcm status --json.
  • Para conferir uma chamada, use o x-fapi-interaction-id dela: finnest opin pcm lookup --interaction-id <x-fapi-interaction-id> ou finnest opin interactions --interaction-id <x-fapi-interaction-id>.
  • A linha Correlation echo today: N differing (P% of today's receipts) mostra quantos recibos de hoje (desde a meia-noite de São Paulo) voltaram com um correlationId diferente do enviado. A API de ingestão (v1.0.13) atribui os itens do recibo pela posição, então o id é só uma conferência: 0% indica que o id foi ecoado (ou que nenhum recibo voltou ainda), 100% indica que o PCM responde com ids próprios (informativo), e uma taxa parcial indica um possível desalinhamento de posição. O doctor mostra a mesma taxa; uma taxa parcial é aviso, nunca falha.

Confira o kid de assinatura em três fontes: o opin_pcm_signing_kid do alvo ativo, a identidade com que o serviço implantado assina e o keystore público da organização no Diretório:

bash
finnest opin pcm doctor

O PCM valida os relatórios com o certificado de assinatura (BRSEAL) cadastrado na organização. O doctor lê o JWKS público da organização (org_jwks_uri, https://keystore.sandbox.directory.opinbrasil.com.br/<org_id>/application.jwks; em produção, keystore.directory.opinbrasil.com.br) e o JWKS de chaves inativas (org_jwks_inactive_uri, .../<org_id>/inactive/application.jwks), como descreve a seção de software statement da área do desenvolvedor do OPIN. Os dois são públicos: não precisa de sessão no Diretório, BRCAC nem TOTP. O kid precisa ser uma chave de assinatura (use: "sig"; chaves enc são ignoradas), não pode estar no JWKS de inativas, e o SHA-256 do DER do seu x5c[0] precisa ser o do certificado em uso. O resultado é um só:

VereditoCódigoSignificado
org-level—O kid é da organização, ativo e do certificado em uso.
inactiveOPIN_PCM_SIGNING_KID_INACTIVEO kid está no JWKS de chaves inativas.
absentOPIN_PCM_SIGNING_KID_ABSENTO kid não é uma chave de assinatura ativa da organização.
certificate-mismatchOPIN_PCM_SIGNING_CERTIFICATE_MISMATCHO kid aponta para outro certificado.
keystore-unreachableOPIN_PCM_KEYSTORE_UNREACHABLEO keystore não respondeu com um JWKS.

O doctor também falha quando o kid do alvo difere do kid implantado (OPIN_PCM_SIGNING_KID_DIVERGED) e avisa quando o envio real está desligado (real sending off: the PCM receives nothing).

A URL do keystore só é montada a partir de um id de organização que seja um UUID. Qualquer outro valor (com /, .. ou ?, por exemplo) é recusado antes de qualquer requisição: o doctor responde OPIN_PCM_ORGANISATION_ID_INVALID e a verificação opin-pcm-signing do deploy falha.

Ligar o envio real ​

  1. Cadastre o BRSEAL no Diretório no nível da organização e guarde o certificado e a chave: finnest secrets write keycloak-brseal-certificate-pem --file <pem> e finnest secrets write keycloak-brseal-private-key-pem --file <pem>.

  2. Veja o kid com finnest opin directory certs e informe-o no alvo, ainda com o envio desligado. Prepare a mudança no configuration workspace e faça o commit, usando a revisão que cada resposta devolve:

    bash
    finnest config workspace open --goal=apply --json
    finnest config workspace stage <workspace> <revisão> opin.pcm-signing-kid <kid>
    finnest config workspace review <workspace> <revisão>
    finnest config workspace commit <workspace> <revisão> review

    Se a resposta listar avisos, reconheça cada um com finnest config workspace acknowledge <workspace> <revisão> <requirement-id> antes do review. O campo grava opin_pcm_signing_kid no alvo ativo.

  3. Rode finnest deploy e depois finnest opin pcm doctor: o veredito precisa ser org-level e o kid do alvo precisa ser o implantado.

  4. Ligue o envio da mesma forma, com opin.pcm-live true (grava opin_pcm_live = true), e rode finnest deploy --preview. A verificação opin-pcm-signing da preparação do deploy aplica a mesma regra ao kid do alvo e ao certificado BRSEAL guardado. Se o veredito não for org-level, o deploy para com DEPLOY_PREFLIGHT_FAILED antes de qualquer alteração, para que o envio real nunca ligue com um kid que o PCM recusa. Com o envio desligado, não há consulta ao keystore nem bloqueio.

  5. Aplique o deploy e confirme em finnest opin pcm status a linha Real sending ON.

Aprovar, reenviar e alterar o modo de envio exigem --yes e o e-mail de quem faz a operação, que o serviço registra:

bash
finnest opin pcm approve <batch-id> --operator <email> --yes
finnest opin pcm resend <batch-id> --operator <email> --yes
finnest opin pcm config --mode manual --interval 15 --operator <email> --yes

resend aceita um lote com falha ou sem confirmação dentro da janela de 180 dias. Se o comando responder OPIN_PCM_SCOPE_DENIED, rode finnest deploy depois de atualizar a CLI, para que o realm conceda os escopos opin:pcm:read e opin:pcm:operate.

A declaração de recertificação OIDF responde 403 ou 503 ​

Na vigilância de conformidade do console Power, só os donos (owner) e administradores (admin) da organização que opera o participante desta implantação declaram uma recertificação OIDF. Como qualquer pessoa pode criar a própria organização no Power, ser dono de outra organização não basta.

  • 503 com operator organization unresolved (Power IAM must hold exactly one self-hosted organization): o Power não encontrou exatamente uma organização auto-hospedada no Power IAM. A organização operadora é a organização auto-hospedada que finnest admin owner create ou o bootstrap da licença provisiona; não há nada a informar no finnest.toml nem no workspace de configuração. Se o dono ainda não foi criado, rode finnest admin owner create.
  • 403 com only the organization that operates this participant declares recertifications: a organização ativa da sessão não é a organização operadora. Troque a organização ativa no console ou peça a um dono ou administrador dela que faça a declaração.

Um finnest.toml que ainda informa power_operator_organization_id em um [profile.<id>] falha com CONFIG_FIELD_RETIRED; rode finnest config retire power.operator-organization-id para remover a chave e confirme de novo o workspace de configuração.

Ler a vigilância também exige que a organização ativa da sessão seja a organização operadora, com qualquer papel menos developer. Fora dela, a leitura recebe 403, e recebe o mesmo 503 descrito acima quando o Power não resolve a organização operadora. Uma sessão sem organização ativa recebe 403 com active organization required, tanto na leitura quanto na declaração. Só a declaração exige, além disso, o papel owner ou admin.

Finnest Power — plataforma Open Finance Brasil e Open Insurance Brasil. Contato: oi@finnest.com.br