← Todos os artigos
Atualizado em May 29, 20265 min read

Unexpected Token u em JSON na posição 0: parseando undefined

O erro «Unexpected token u» significa que você chamou JSON.parse(undefined). Aprenda por que undefined vira "undefined", como se proteger e um helper de parse seguro.

SyntaxError: Unexpected token 'u', "undefined" is not valid JSON (engines mais antigas: Unexpected token u in JSON at position 0) quase sempre significa que você chamou JSON.parse(undefined). JavaScript transforma undefined em string como o texto "undefined", e o parser engasga no u inicial. Aqui vai por quê e como consertar.

Como o erro aparece

// V8 (Chrome / Node / Edge)
SyntaxError: "undefined" is not valid JSON
SyntaxError: Unexpected token 'u', "undefined" is not valid JSON
SyntaxError: Unexpected token u in JSON at position 0   // V8 mais antigo

// Firefox
SyntaxError: JSON.parse: unexpected character at line 1 column 1

// Safari
SyntaxError: JSON Parse error: Unexpected identifier "undefined"

O u na posição 0 é a primeira letra da string "undefined" —— o parser nunca recebeu dado real.

Por que acontece: você parseou undefined

JSON.parse() força o argumento para string primeiro. Passe undefined e ele parseia o texto literal "undefined", que não é JSON válido. O valor é undefined geralmente porque:

  • Uma variável ou argumento de função nunca foi atribuída
  • Uma propriedade de objeto não existe (typo ou shape errado): obj.missing
  • Um valor async ainda não está pronto (parseado antes do await)
  • Uma função sem return foi usada como fonte

Exemplo quebrado

const cached = localStorage.getItem('settings'); // key ausente → null, OK
const draft  = window.appState?.draft;            // propriedade ausente → undefined
const data   = JSON.parse(draft);                 // ❌ "undefined" is not valid JSON

Exemplo consertado

// Guard antes de parsear
const data = draft ? JSON.parse(draft) : null;

// Ou um helper seguro
function safeParse(text, fallback = null) {
  if (typeof text !== 'string' || text.trim() === '') return fallback;
  try { return JSON.parse(text); } catch { return fallback; }
}
const data2 = safeParse(draft);

Nota: JSON.parse(null) não lança —— retorna null —— e localStorage.getItem() retorna null (não undefined) para uma key ausente. Então um erro u aponta especificamente para um valor undefined, não uma key de storage ausente.

SyntaxError vs TypeError: por que você pega esse

Detalhe sutil mas útil: JSON.parse(undefined) lança um SyntaxError, não um TypeError. Por quê? Porque a spec diz que JSON.parse primeiro força o argumento para string ("undefined") e então parseia essa string. O erro é «essa string não é JSON válido», não «você passou o tipo errado». Por isso JSON.parse(undefined) e JSON.parse("undefined") produzem a mesma mensagem em posição 0.

Contraste com APIs que realmente fazem checagem de tipo, como JSON.stringify(BigInt(1)) → TypeError, ou JSON.parse(Symbol()) → TypeError (Symbols não podem ser forçados para string). Se você captura erros de parse, restrinja com err instanceof SyntaxError para tratar dado ruim separado de argumentos ruins.

Como consertar —— passo a passo

  1. Logue a entrada:console.log(typeof src, src) bem antes do parse. Se imprimir undefined, esse é o culpado.
  2. Rastreie onde deveria ser setado —— um campo de state não inicializado, um argumento ausente, ou uma propriedade que não existe no objeto.
  3. Adicione um guard (if (src)) ou um fallback safeParse pra um valor ausente não chegar até JSON.parse().
  4. Se for async, garanta que você await no valor antes de parsear.

Perguntas frequentes

O que significa «Unexpected token u in JSON at position 0»?

Você passou undefined pro JSON.parse(). Vira a string "undefined", e o u inicial não é um caractere de início válido de JSON.

É a mesma coisa que os erros «token o» ou «token <»?

Mesma família, valor diferente. u = undefined; token o = um objeto transformado em string como [object Object]; token < = uma resposta HTML. O caractere nomeado te diz o que foi passado de verdade.

Por que JSON.parse(null) não lança o mesmo erro?

"null" é JSON válido, então JSON.parse(null) retorna null. Só undefined (→ "undefined") dispara o erro u.

Conserte agora