---
title: "undefined: variable ou function em Go"
url: "https://golang.com.br/erros/undefined-variable-function/"
markdown_url: "https://golang.com.br/erros/undefined-variable-function.MD"
description: "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."
date: "2026-05-12"
author: "Golang Brasil"
---

# 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](/aprenda/go-modules/).

---

## 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:

```go
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:

```go
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](/aprenda/go-modules-na-pratica/) em Go:

```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
}
```

```go
// 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:

```go
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:

```bash
# 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:

```go
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

```go
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)

```go
// 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:

```go
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:

```bash
# Compila todos os arquivos do pacote
go run .

# Ou para build
go build .
```

### Solução 5: Adicionar o Import

Use seu editor com [gopls](/blog/melhores-ferramentas-go-2026/) configurado, que adiciona imports automaticamente. Ou adicione manualmente:

```go
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](/blog/melhores-ferramentas-go-2026/).

2. **Lembre-se da regra de exportação** — maiúscula = exportado, minúscula = privado ao pacote. Consulte [interfaces em Go](/aprenda/golang-interfaces/) 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](/aprenda/testes-go/).

4. **Entenda o escopo** — variáveis existem apenas dentro do bloco `{}` onde foram declaradas. Revise nosso guia de [Go para iniciantes](/aprenda/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](/erros/declared-not-used/) — o inverso: variável existe mas não é usada
- [cannot use X as type Y](/erros/cannot-use-x-as-type-y/) — quando o nome existe mas o tipo não bate
- [import cycle not allowed](/erros/import-cycle-not-allowed/) — problemas com organização de pacotes
- [Go Modules na Prática](/aprenda/go-modules-na-pratica/) — como organizar pacotes corretamente