Como ler uma stack trace Java e encontrar a causa do erro

Atualizado em 3 de novembro de 2026 · Leitura de 5 min

Edson Feitosa de Oliveira Junior Fundador e Engenheiro Líder · PruPru Digital Services

Ler uma stack trace Java assusta no começo, porque, quando uma aplicação falha, ela costuma despejar dezenas ou centenas de linhas no console. Para quem está começando, aquele bloco de texto parece incompreensível, e a reação comum é copiar tudo e procurar na internet. Mas a stack trace é, na verdade, um mapa preciso do problema: ela diz qual erro aconteceu, em qual linha e qual caminho o programa percorreu até chegar lá. Saber lê-la é uma das habilidades que mais aceleram um desenvolvedor.

O que é uma stack trace

Quando um método chama outro, que chama outro, o Java empilha essas chamadas (a pilha de execução, ou call stack). Quando uma exceção não é tratada, o Java imprime essa pilha no momento do erro: do ponto exato onde a exceção ocorreu até o início da execução.

Anatomia de uma stack trace Java

Exception in thread "main" java.lang.NullPointerException: Cannot invoke "String.length()" because "nome" is null
    at br.com.loja.Cliente.validarNome(Cliente.java:42)
    at br.com.loja.ClienteService.cadastrar(ClienteService.java:18)
    at br.com.loja.Main.main(Main.java:9)

Leia assim:

1. Primeira linha: o tipo da exceção (NullPointerException) e a mensagem. Nas versões modernas do Java, a mensagem já explica qual variável era nula.
2. Linhas com at: cada uma é um método na pilha, com classe, método, arquivo e número da linha.
3. A primeira linha at é onde o erro aconteceu: Cliente.java, linha 42.
4. As linhas seguintes mostram quem chamou: ClienteService.cadastrar, chamado por Main.main.

Neste caso, a pergunta certa é: por que nome chegou nulo ao método validarNome? A resposta provavelmente está em quem chamou, na linha 18 de ClienteService.

Encontre a primeira linha do seu código

Em aplicações reais, a pilha mistura o seu código com o de frameworks e bibliotecas (Spring, Hibernate, Tomcat). A regra prática: procure a primeira linha que pertence ao seu pacote (por exemplo, br.com.loja). As linhas de framework mostram por onde a requisição passou, mas a causa quase sempre está no seu código.

Caused by: a causa real está no fim

Exceções muitas vezes são "embrulhadas" em outras. A stack trace mostra a cadeia com Caused by:

org.springframework.beans.factory.BeanCreationException: Error creating bean with name 'clienteService'
    ...
Caused by: org.springframework.beans.factory.UnsatisfiedDependencyException: ...
    ...
Caused by: java.lang.IllegalStateException: Propriedade app.jwt.secret não configurada
    at br.com.loja.config.JwtConfig.<init>(JwtConfig.java:21)

Leia o último Caused by. Ele é a causa raiz. No exemplo, a aplicação não subiu porque faltava uma variável de configuração; veja variáveis de ambiente e segredos.

A expressão ... 25 more indica que as linhas restantes são iguais às da exceção acima e foram omitidas.

Exceções mais comuns e o que costumam significar

Erros comuns no Spring Boot

• Port 8080 was already in use: outra aplicação já usa a porta. Encerre o processo ou mude server.port.
• Failed to configure a DataSource: falta a configuração do banco de dados, ou a dependência do banco foi incluída sem ser usada.
• No qualifying bean of type: o Spring não encontrou uma classe para injetar. Verifique anotações como @Service e @Repository e se a classe está em um pacote abaixo da classe principal.
• LazyInitializationException: acesso a uma relação do JPA depois que a sessão foi fechada, geralmente ao montar a resposta da API. Use DTOs e busque os dados necessários na consulta.
• HttpMessageNotReadableException: o JSON enviado está malformado ou não corresponde ao objeto esperado. Veja JSON para iniciantes.

Para montar a base de uma API, veja sua primeira API com Spring Boot.

Um roteiro para depurar

1. Leia a mensagem com atenção. Muitas vezes ela já diz o problema.
2. Ache o último Caused by.
3. Ache a primeira linha do seu código naquela exceção.
4. Abra o arquivo na linha indicada e pergunte: quais valores poderiam causar esse erro aqui?
5. Reproduza o erro com o menor caso possível.
6. Use o depurador da IDE: coloque um breakpoint na linha, rode em modo debug e inspecione as variáveis. É muito mais eficiente que espalhar System.out.println.
7. Corrija e escreva um teste que reproduz o problema, para que ele não volte. Veja testes automatizados com JUnit.

Stack traces em produção

Em produção, as stack traces devem ir para os logs, nunca para a resposta da API, porque revelam detalhes internos que ajudam atacantes. Registre a exceção completa no log e devolva ao cliente uma mensagem genérica com um identificador da requisição. Veja logs em produção e códigos de status HTTP.

Pedindo ajuda do jeito certo

Ao perguntar a um colega, em um fórum ou a uma ferramenta de IA, envie a stack trace completa (como texto, não print), o trecho de código das linhas citadas e o que você já tentou. Remova senhas, tokens e dados pessoais antes de colar qualquer coisa. Uma boa pergunta costuma render uma resposta em minutos.

Perguntas frequentes