Troubleshooting

A maioria dos problemas de LTI 1.3 cai em uma destas categorias: assinatura inválida, claims faltando ou registro desincronizado entre LMS e tool.

401 Unauthorized no /lti/launch

Possíveis causas:

“LTI id_token verification failed: signature verification failed”

A assinatura do id_token não bate com nenhuma chave do JWKS do LMS.

• Confirme que o jwks_url registrado na Árvore é o JWKS do LMS, não o nosso
• Limpe o cache de JWKS reiniciando os pods do api-arvore (cache de 1h)
• Verifique se o LMS rotacionou as chaves recentemente

”Deployment ID mismatch”

O deployment_id registrado na Árvore não bate com o que vem no claim. Geralmente acontece quando o LMS gera um novo deployment_id ao reinstalar a tool. Atualize o registro na Árvore.

”Invalid or replayed nonce”

O nonce enviado pelo LMS já foi consumido (mais de um launch com mesmo nonce) ou expirou (TTL 10min). Causas comuns:

• Usuário fez double-click no link
• Cache de browser repetindo a request
• Diferença grande de relógio entre LMS e Árvore

”Unsupported LTI message type”

A Árvore só aceita LtiResourceLinkRequest por enquanto. LtiDeepLinkingRequest ainda não é suportado.

Erro: “No platform found for issuer”

A combinação (iss, client_id, deployment_id) não está registrada na Árvore. Entre em contato com o time da Árvore para confirmar que o deployment do seu LMS foi cadastrado.

Aluno entra como usuário errado

Cenário: Maria clica no link do LMS e a Árvore loga como João.

Causas possíveis:

• O LMS está enviando sub igual para múltiplos usuários (bug do LMS, raro)
• Existe uma conta antiga da Árvore com o mesmo email que veio no claim, e o lti_user_links não estava preenchido — o fallback por email pegou a conta errada

Mitigação:

1. Apague o registro errado em lti_user_links para forçar nova resolução
2. Confirme com o LMS que o claim email é o email institucional do aluno

NRPS sync falha silenciosamente

O cron loga warnings mas não para o resto da execução. Procure no Datadog/SigNoz por:

NRPS sync failed for platform=<id>

Causas mais comuns:

• auth_token_url ausente no registro da plataforma
• LMS não habilitou o escopo contextmembership.readonly para a Árvore
• Chave da Árvore foi rotacionada e o LMS ainda não buscou o novo JWKS

Como debugar localmente

Use o LTI Reference Implementation Tester do 1EdTech como Platform fake. Ele permite gerar id_token válidos e testar o launch sem precisar de um LMS real.

1. Registre a Árvore como tool no LTI RI (ele vai gerar issuer, client_id, deployment_id)
2. Compartilhe esses valores com o time da Árvore para registrar o deployment
3. Use o tester para emitir launches e validar o fluxo completo