Como corrigir a variável ReferenceError não capturada não está definida em JavaScript

O erroReferenceError não capturado: x não está definido em JavaScript significa que você está tentando usar uma variável ou função que não existe no escopo atual. É um dos erros de JavaScript mais comuns. Aqui estão todas as causas e soluções.

O que esse erro significa

JavaScript procurou por uma variável ou função chamadax mas não consegui encontrá-lo no escopo acessível. Ou nunca foi declarado, está fora do escopo, há um erro de digitação ou o script que o define ainda não foi carregado. O erro nomeia o identificador específico que não foi possível encontrar – comece por aí.

Causa 1: Variável nunca declarada

// 🐛 Using a variable that was never declared
console.log(username);   // ReferenceError: username is not defined

// ✅ Declare it first
const username = 'Alice';
console.log(username);   // works

Causa 2: Erro de digitação no nome da variável

// 🐛 Declared as 'userName' but used as 'username'
const userName = 'Alice';
console.log(username);   // ReferenceError - case mismatch!

// ✅ Match the exact name (JavaScript is case-sensitive)
const userName = 'Alice';
console.log(userName);   // works

// Common typos: case differences, misspellings, wrong variable

Causa 3: Fora do escopo

// 🐛 Variable declared in a different scope
function setup() {
  const config = { debug: true };
}
console.log(config);   // ReferenceError - config is inside setup()

// ✅ Declare it in an accessible scope, or return it
function setup() {
  return { debug: true };
}
const config = setup();
console.log(config);   // works

// 🐛 Block scope with let/const
if (true) {
  let temp = 5;
}
console.log(temp);   // ReferenceError - temp only exists in the block

// ✅ Declare in the outer scope if you need it there
let temp;
if (true) { temp = 5; }
console.log(temp);   // works

Causa 4: Ordem de carregamento do script (navegador)

<!-- 🐛 Using a function before its script loads -->
<script>
  myFunction();   // ReferenceError if library.js hasn't loaded yet
</script>
<script src="library.js"></script>

<!-- ✅ Load the dependency FIRST -->
<script src="library.js"></script>
<script>
  myFunction();   // now library.js is loaded
</script>

<!-- ✅ Or use defer to control load order -->
<script src="library.js" defer></script>
<script src="main.js" defer></script>
<!-- deferred scripts run in order, after HTML parses -->

Causa 5: Acessando Antes da Declaração (Zona Temporal Morta)

// 🐛 let/const can't be used before their declaration
console.log(count);   // ReferenceError (temporal dead zone)
let count = 5;

// ✅ Declare before using
let count = 5;
console.log(count);   // works

// Note: var is hoisted (returns undefined, not an error),
// but let/const throw a ReferenceError if accessed before declaration

Causa 6: Importação ausente (módulos)

// 🐛 Using something from another module without importing it
console.log(helper());   // ReferenceError: helper is not defined

// ✅ Import it
import { helper } from './utils.js';
console.log(helper());   // works

Causa 7: Variável em um escopo de arquivo/módulo diferente

// 🐛 In ES modules, top-level variables are module-scoped, not global
// file1.js
const apiKey = 'secret';

// file2.js
console.log(apiKey);   // ReferenceError - not shared between modules

// ✅ Export and import it
// file1.js
export const apiKey = 'secret';
// file2.js
import { apiKey } from './file1.js';

Etapas de depuração

1. Leia o erro — nomeia o identificador exato que não está definido
2. Verifique se há erros de digitação — distinção entre maiúsculas e minúsculas e ortografia (causa mais comum)
3. Verifique se está declarado – existe um const/let/var/function/import para isso?
4. Verifique o escopo — a variável está acessível onde você a está usando?
5. Verifique a ordem de carregamento/declaração — é usado antes de ser definido ou carregado?
6. Verifique as importações — em módulos, é importado de onde está definido?

Perguntas Frequentes

P: Qual é a diferença entre “não definido” e “indefinido”?
R: “x não está definido” (ReferenceError) significa que a variável não existe no escopo. “indefinido” significa que a variável existe, mas não tem nenhum valor atribuído. Problemas diferentes: “não definido” significa declará-lo ou corrigir escopo/erro de digitação; “indefinido” significa atribuir um valor a ele.

P: Por que funciona algumas vezes, mas outras não?
R: Freqüentemente, ordem ou tempo de carregamento do script – uma variável/função de outro script pode não ter sido carregada ainda quando seu código é executado. Usardefer em scripts, certifique-se de que as dependências sejam carregadas primeiro ou aguarde o evento DOM/load. ReferenceErrors intermitentes geralmente significam um problema de tempo/ordem.

P: Declarei a variável, mas ainda recebo “não definido”. Por que?
R: Verifique o escopo (está declarado em um escopo acessível, não dentro de uma função ou bloco do qual você está fora?), verifique se há erros de digitação (diferencia maiúsculas de minúsculas) e nos módulos verifique se você o importou. Verifique também se você não está acessando let/const antes de sua linha de declaração (zona morta temporal).

P: Como faço para corrigir “não definido” para uma função de biblioteca?
R: Certifique-se de que o script da biblioteca seja carregado ANTES do código que o utiliza. Coloque o<script>da biblioteca marque primeiro ou usedefer em ambos os scripts (eles são executados em ordem). Para módulos, importe a função. A biblioteca deve estar disponível antes de você ligar para ela.

P: Por que let e const lançam, mas var não?
A: var é içado e inicializado como indefinido, portanto, acessá-lo antes da declaração retornar indefinido (sem erro). let econst são içados, mas não inicializados – acessá-los antes de sua linha de declaração gerar um ReferenceError (a “zona morta temporal”). Declare let/const antes de usá-los.

Conclusão

“ReferenceError não capturado: x não está definido” significa que o JavaScript não consegue encontrar uma variável ou função no escopo acessível. As causas:a variável nunca foi declarada, há um erro de digitação (verifique a distinção entre maiúsculas e minúsculas), está fora do escopo, um script ainda não foi carregado, foi acessado antes de sua declaração let/const ou uma importação de módulo está faltando. A abordagem de depuração: leia o erro (ele nomeia o identificador), verifique primeiro se há erros de digitação (a causa mais comum), verifique se ele está declarado e no escopo, verifique a ordem de carregamento/declaração e confirme as importações nos módulos. Depois de garantir que o identificador esteja declarado, escrito corretamente, no escopo e disponível quando acessado, o erro será resolvido. Quase sempre é um erro de digitação, um problema de escopo ou um problema de ordem de carregamento – resolva-os sistematicamente.