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:

package main

import "fmt"

func main() {
    // ERRO: undefined: mensagem
    fmt.Println(mensagem)
}

2. Erro de Digitação

Go é case-sensitive. Nome, nome e NOME são identificadores completamente diferentes:

package main

import "fmt"

func main() {
    nome := "Go"
    // ERRO: undefined: Nome (N maiúsculo)
    fmt.Println(Nome)
}

3. Nome Não Exportado de Outro Pacote

Em Go, apenas identificadores que começam com letra maiúscula são exportados (visíveis fora do pacote). Esta é uma regra fundamental da organização de pacotes em Go:

// arquivo: utils/math.go
package utils

// calcular NÃO é exportado (letra minúscula)
func calcular(a, b int) int {
    return a + b
}

// Calcular É exportado (letra maiúscula)
func Calcular(a, b int) int {
    return a + b
}

// arquivo: main.go
package main

import "meuapp/utils"

func main() {
    // ERRO: undefined: utils.calcular
    resultado := utils.calcular(1, 2)

    // OK: Calcular é exportado
    resultado := utils.Calcular(1, 2)
}

4. Variável Fora de Escopo

Variáveis declaradas dentro de um bloco (if, for, switch) só existem dentro daquele bloco:

package main

import "fmt"

func main() {
    if true {
        msg := "dentro do if"
        fmt.Println(msg)
    }
    // ERRO: undefined: msg (fora do escopo do if)
    fmt.Println(msg)
}

5. Função em Outro Arquivo do Mesmo Pacote

Se você tem múltiplos arquivos .go no mesmo pacote e executa apenas um deles:

# ERRADO: só compila main.go, ignora helpers.go
go run main.go

# CERTO: compila todos os arquivos .go do diretório
go run .

6. Import Não Realizado

Usar um tipo ou função de um pacote sem importá-lo:

package main

// Esqueceu de importar "strings"

func main() {
    // ERRO: undefined: strings.Contains
    resultado := strings.Contains("golang", "go")
}

Como Resolver

Solução 1: Declarar a Variável

package main

import "fmt"

func main() {
    mensagem := "Olá, Go!" // Declara a variável
    fmt.Println(mensagem)
}

Solução 2: Exportar o Nome (Letra Maiúscula)

// utils/math.go
package utils

// Exportado — visível fora do pacote
func Calcular(a, b int) int {
    return a + b
}

Solução 3: Ajustar o Escopo

Declare a variável no escopo correto:

package main

import "fmt"

func main() {
    var msg string // Declarada no escopo da função

    if true {
        msg = "dentro do if"
    }

    fmt.Println(msg) // Funciona!
}

Solução 4: Usar go run . ou go build .

Sempre compile o pacote inteiro:

# Compila todos os arquivos do pacote
go run .

# Ou para build
go build .

Solução 5: Adicionar o Import

Use seu editor com gopls configurado, que adiciona imports automaticamente. Ou adicione manualmente:

package main

import (
    "fmt"
    "strings"
)

func main() {
    resultado := strings.Contains("golang", "go")
    fmt.Println(resultado) // true
}

Dicas para Evitar Este Erro

1. Configure o gopls no seu editor — ele detecta referências indefinidas em tempo real e sugere imports automaticamente. Veja nosso guia de ferramentas essenciais para Go.

2. Lembre-se da regra de exportação — maiúscula = exportado, minúscula = privado ao pacote. Consulte interfaces em Go para entender como isso afeta implementações.

3. Use go vet — esta ferramenta detecta problemas comuns. É parte do fluxo padrão de testes em Go.

4. Entenda o escopo — variáveis existem apenas dentro do bloco {} onde foram declaradas. Revise nosso guia de Go para iniciantes para uma explicação detalhada.

5. Compile com go build . — não compile arquivos individuais quando seu pacote tem múltiplos arquivos.

Erros Relacionados

• declared and not used — o inverso: variável existe mas não é usada
• cannot use X as type Y — quando o nome existe mas o tipo não bate
• import cycle not allowed — problemas com organização de pacotes
• Go Modules na Prática — como organizar pacotes corretamente