Erros Comuns em Go: Guia de Referência
Quando você programa em Go, inevitavelmente encontra mensagens de erro — seja do compilador, do runtime ou de ferramentas como o go vet e o race detector. Este guia reúne os erros mais frequentes que desenvolvedores Go enfrentam no dia a dia, com explicações claras e soluções práticas.
Se você está começando com Go, recomendamos primeiro ler nosso guia de tratamento de erros em Go, que explica os fundamentos da abordagem de erros da linguagem. Este guia complementa aquele conteúdo, focando nas mensagens de erro específicas que você encontra durante o desenvolvimento.
Erros de Compilação
Estes erros aparecem antes do seu programa executar. O compilador do Go é rigoroso e detecta muitos problemas antecipadamente.
Tipos e Valores
cannot use X as type Y — Quando você tenta atribuir ou passar um valor de tipo incompatível. Um dos erros mais frequentes, especialmente para quem vem de linguagens com tipagem dinâmica.
declared and not used — Variáveis declaradas que não são utilizadas. Exclusivo do Go e uma surpresa comum para iniciantes.
missing return at end of function — Quando uma função declara valores de retorno, mas nem todos os caminhos de execução retornam um valor.
multiple-value in single-value context — Quando você tenta usar o resultado de uma função que retorna múltiplos valores em um contexto que espera apenas um.
Referências e Escopo
undefined: variable or function — Referências a variáveis, funções ou campos que não existem no escopo atual, incluindo nomes não exportados de outros pacotes.
import cycle not allowed — Dependência circular entre pacotes. O compilador do Go não permite ciclos de importação.
Iteração
- cannot range over X — Quando você tenta usar
rangecom um tipo que não suporta iteração.
Erros de Runtime
Estes erros acontecem durante a execução do programa. São mais difíceis de prever porque dependem dos dados e do estado do programa.
nil pointer dereference — O temido panic por acessar um ponteiro nulo. Uma das causas mais comuns de crashes em programas Go.
all goroutines are asleep — deadlock! — Quando todas as goroutines do programa estão bloqueadas esperando umas pelas outras.
data race detected — Acesso concorrente a memória compartilhada sem sincronização, detectado pelo race detector do Go.
Como Usar Este Guia
Cada página de erro contém:
- A mensagem de erro exata — para você identificar rapidamente
- O que causa o erro — explicação clara do motivo
- Código de exemplo — reproduzindo o erro
- Como resolver — soluções práticas com código corrigido
- Dicas adicionais — boas práticas para evitar o erro no futuro
Recursos Relacionados
Se você quer aprofundar seus conhecimentos sobre erros em Go, confira estes recursos:
- Tratamento de Erros em Go: Guia Definitivo — Fundamentos de error handling
- Testes em Go: Guia Completo — Como testar seu código e prevenir erros
- Go para Iniciantes — Primeiros passos na linguagem
- Concorrência em Go — Entenda goroutines e channels para evitar deadlocks e race conditions
- Interfaces em Go — Compreenda a interface
errore tipagem em Go - Perguntas de Entrevista Go — Erros e error handling são temas frequentes em entrevistas
cannot range over em Go
Resolva o erro 'cannot range over' em Go. Entenda quais tipos suportam range, como iterar corretamente e use iteradores customizados no Go.
cannot range over em Go
O erro “cannot range over X” aparece quando você tenta usar for range com um tipo que não suporta iteração. O range do Go funciona apenas com tipos específicos, e usá-lo com qualquer outro tipo resulta em erro de compilação.
A Mensagem de Erro
./main.go:10:15: cannot range over num (variable of type int)
./main.go:12:15: cannot range over usuario (variable of type Usuario)
Tipos que Suportam range
Em Go, range funciona apenas com estes tipos:
| Tipo | Produz | Exemplo |
|---|---|---|
array / slice | índice, valor | for i, v := range []int{1,2,3} |
string | índice, rune | for i, r := range "Go" |
map | chave, valor | for k, v := range map[string]int{} |
channel | valor | for v := range ch |
int (Go 1.22+) | índice | for i := range 5 |
func(yield) (Go 1.23+) | valores do yield | for v := range iterador |
Causas Comuns
1. Range sobre Tipo Numérico (antes do Go 1.22)
Antes do Go 1.22, não era possível usar range com inteiros:
cannot use X as type Y em Go
Entenda e resolva o erro 'cannot use X as type Y' em Go. Causas comuns, exemplos de código e soluções práticas para incompatibilidade de tipos.
cannot use X as type Y em Go
O erro “cannot use X (variable of type A) as type B” é uma das mensagens mais frequentes que desenvolvedores Go encontram. Ele aparece quando você tenta usar um valor de um tipo onde o compilador espera outro tipo incompatível.
Go é uma linguagem com tipagem estática forte, o que significa que o compilador verifica todos os tipos em tempo de compilação. Diferente de linguagens como Python ou JavaScript, Go não faz conversões implícitas entre tipos — e isso é uma escolha deliberada de design.
data race detected em Go
Resolva 'data race detected' em Go. Aprenda a usar o race detector, identificar condições de corrida e proteger dados com mutex e channels.
data race detected em Go
Uma data race (condição de corrida de dados) ocorre quando duas ou mais goroutines acessam a mesma variável de memória simultaneamente, e pelo menos uma delas está escrevendo. O Go possui um race detector integrado que detecta essas condições em tempo de execução, emitindo o aviso “WARNING: DATA RACE” e detalhando exatamente onde o acesso concorrente acontece.
Data races são bugs sérios: podem causar corrupção de dados, panics inesperados e comportamentos não determinísticos que são extremamente difíceis de reproduzir e debugar.
deadlock — all goroutines are asleep em Go
Resolva o erro 'all goroutines are asleep - deadlock!' em Go. Aprenda a identificar causas de deadlock com channels, mutexes e WaitGroups.
deadlock — all goroutines are asleep em Go
O erro “fatal error: all goroutines are asleep - deadlock!” é um panic do runtime do Go que acontece quando todas as goroutines do programa estão bloqueadas esperando por algo que nunca vai acontecer. O runtime detecta que nenhuma goroutine pode prosseguir e encerra o programa.
Este é um dos erros mais comuns ao trabalhar com concorrência em Go, especialmente com channels e mutexes.
declared and not used em Go
Resolva o erro 'declared and not used' em Go. Entenda por que Go não permite variáveis sem uso e conheça as formas corretas de lidar com isso.
declared and not used em Go
O erro “declared and not used” é único do Go e uma das primeiras surpresas para quem vem de outras linguagens. Enquanto a maioria das linguagens apenas emite um warning para variáveis não utilizadas, Go trata isso como um erro de compilação — seu programa simplesmente não compila.
Essa decisão de design é intencional: código morto dificulta a leitura e manutenção, e o compilador do Go prefere ser rigoroso do que permissivo.
import cycle not allowed em Go
Resolva o erro 'import cycle not allowed' em Go. Aprenda a identificar e quebrar dependências circulares entre pacotes com exemplos práticos.
import cycle not allowed em Go
O erro “import cycle not allowed” acontece quando dois ou mais pacotes dependem um do outro, criando um ciclo de importação. O compilador Go proíbe rigorosamente dependências circulares — se o pacote A importa o pacote B e o pacote B importa o pacote A (diretamente ou por meio de outros pacotes), seu código não compila.
Essa restrição é uma decisão de design que garante compilação rápida e uma arquitetura de dependências clara. Resolver ciclos de importação geralmente resulta em código melhor estruturado.
missing return at end of function em Go
Resolva o erro 'missing return at end of function' em Go. Entenda por que o compilador exige retorno em todos os caminhos e como corrigir.
missing return at end of function em Go
O erro “missing return at end of function” aparece quando o compilador do Go detecta que uma função declara valores de retorno, mas nem todos os caminhos de execução terminam com um return. O compilador exige que toda função com retorno declarado retorne um valor em todos os caminhos possíveis.
A Mensagem de Erro
./main.go:12:1: missing return at end of function
Causas Comuns
1. Retorno Apenas dentro de Condição
O caso mais frequente — retornar apenas dentro de um if sem cobrir o else:
multiple-value in single-value context em Go
Resolva o erro 'multiple-value in single-value context' em Go. Aprenda a lidar com funções que retornam múltiplos valores corretamente.
multiple-value in single-value context em Go
O erro “multiple-value X() (untyped nil, error) in single-value context” aparece quando você tenta usar o resultado de uma função que retorna múltiplos valores em um contexto que espera apenas um valor. Em Go, funções frequentemente retornam dois ou mais valores (especialmente o padrão (valor, error)), e o compilador exige que você trate todos eles.
A Mensagem de Erro
./main.go:10:7: multiple-value os.Open() (untyped nil, error) used in single-value context
./main.go:15:12: multiple-value strconv.Atoi() (int, error) used in single-value context
Causas Comuns
1. Atribuição Simples de Função com Dois Retornos
O caso mais comum — tentar capturar o resultado em uma única variável:
nil pointer dereference em Go
Resolva o panic 'nil pointer dereference' em Go. Entenda causas de ponteiro nulo, como prevenir e técnicas para debug de panics no runtime.
nil pointer dereference em Go
O “runtime error: invalid memory address or nil pointer dereference” é um dos panics mais comuns em programas Go. Ele acontece quando você tenta acessar um campo, chamar um método ou desreferenciar um ponteiro que tem valor nil — ou seja, não aponta para nenhum endereço de memória válido.
Diferente de linguagens com exceções como Java (NullPointerException) ou C# (NullReferenceException), em Go esse erro causa um panic que, se não recuperado, derruba o programa inteiro.
undefined: variable ou function em Go
Resolva o erro 'undefined' em Go. Saiba por que variáveis, funções e campos aparecem como indefinidos e como corrigir referências e exportação.
undefined: variable ou function em Go
O erro “undefined: X” aparece quando o compilador Go não encontra uma variável, função, tipo ou constante com o nome que você está tentando usar. É um dos erros mais comuns para quem está começando com Go, mas também pode pegar desenvolvedores experientes de surpresa — especialmente quando envolve exportação de nomes entre pacotes.
A Mensagem de Erro
./main.go:10:2: undefined: minhaVariavel
./main.go:15:5: undefined: calcular
./handler.go:8:12: undefined: MeuTipo
Causas Comuns
1. Variável Não Declarada
O caso mais simples — você está usando um nome que nunca foi declarado: