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

Caractere de escape inválido em JSON: causas, exemplos e correções

Corrija erros "bad escaped character in JSON" causados por escapes \x, caminhos Windows, regex, \u malformado e JSON codificado duas vezes.

SyntaxError: Bad escaped character in JSON at position N significa que o parser encontrou uma barra invertida (\) dentro de uma string JSON e que o caractere seguinte não é um dos escapes que o JSON permite. Segundo a seção 7 da RFC 8259, strings JSON podem escapar aspas duplas, a própria barra invertida, a barra normal, os escapes de controle b, f, n, r, t ou um escape Unicode escrito como u seguido por exatamente quatro dígitos hexadecimais.

Na depuração real, esse erro normalmente vem de um valor copiado: um caminho Windows (C:\Users\Ada), um escape de JavaScript ou shell (\x1b), um padrão de regex (\d+), um escape Unicode ao estilo Python (\U0001F600) ou uma string parcialmente desescapada a partir de um log. A correção não é "apagar as barras invertidas". A correção é decidir qual deve ser o valor final da string e então escrever o texto JSON que representa esse valor.

Este guia foca no texto de erro do JSON.parse() do JavaScript, mas a mesma regra vale para json.loads() do Python, encoding/json do Go, JSON.parse do Ruby, json_decode do PHP, jq, jsonb do Postgres e para a maioria dos parsers JSON estritos.

Qual erro de string é este?

A correção em 30 segundos

  1. Vá até a position, line ou column reportada.
  2. Olhe um caractere antes dela em busca de uma barra invertida.
  3. Verifique o caractere depois da barra invertida.
  4. Se a barra invertida faz parte do dado, escreva-a como \\.
  5. Se o escape pertence a outra linguagem (\x, \d, \U), traduza-o para a sintaxe JSON.
  6. Se a barra invertida só foi copiada de uma linha de log entre aspas, analise uma camada em vez de removê-la com regex.

Exemplo:

{"path":"C:\Users\Ada\file.json"}
           ^
           U não é válido após uma barra invertida em JSON

Texto JSON correto:

{
  "path": "C:\\Users\\Ada\\file.json"
}

Após o parsing, o valor real na aplicação continua sendo:

C:\Users\Ada\file.json

As barras invertidas duplicadas só existem no texto JSON.

Como o erro aparece

Motores diferentes usam textos ligeiramente diferentes:

// V8: Chrome, Node.js, Edge
SyntaxError: Bad escaped character in JSON at position 12

// Firefox
SyntaxError: JSON.parse: bad escaped character at line 1 column 13 of the JSON data

// Safari
SyntaxError: JSON Parse error: Invalid escape character \x

O position do V8 geralmente aponta para o caractere depois da barra invertida, não para a própria barra. Neste JSON quebrado, o caractere reportado é o U em \Users:

{"path":"C:\Users\Ada\file.json"}
           ^^
           \U é o escape ruim

Portanto, quando a mensagem diz position 12, inspecione uma pequena janela antes e depois da posição 12. O caractere ruim é útil, mas é a barra invertida antes dele que explica o bug.

Os únicos escapes que o JSON aceita

Dentro de uma string JSON, uma barra invertida só pode introduzir estes escapes:

Escape JSON Caractere analisado Notas
\" " Necessário para aspas duplas dentro de uma string JSON
\\ \ Necessário para uma barra invertida literal
\/ / Opcional; / também é válido sem escape
\b Backspace U+0008
\f Form feed U+000C; é por isso que \file é perigoso em caminhos Windows
\n Nova linha U+000A
\r Retorno de carro U+000D
\t Tabulação U+0009
\uXXXX Unidade de código Unicode Exatamente quatro dígitos hexadecimais depois do u minúsculo

Todo o resto é JSON inválido: \x, \', \d, \s, \w, \0, \v, \e, \U, \u{1F600}, \N{...}, \cA e escapes Unicode curtos como \u12.

Tabela de correção rápida

Use esta tabela quando você já sabe qual deve ser o valor final.

Texto JSON quebrado Por que falha Texto JSON válido
{ "path": "C:\Users\Ada\file.json" } \U e \A são inválidos; \f é válido mas vira form feed, não separador de caminho. { "path": "C:\\Users\\Ada\\file.json" }
{ "path": "C:/Users/Ada/file.json" } Isto não falha. Barras normais não precisam ser escapadas. Mantenha se o consumidor aceitar barras normais.
{ "color": "\x1b[32mOK\x1b[0m" } JSON não tem escape \xNN. { "color": "\u001b[32mOK\u001b[0m" }
{ "name": "O\'Brien" } Apóstrofos não precisam ser escapados em strings JSON. { "name": "O'Brien" }
{ "pattern": "^\d{4}-\d{2}-\d{2}$" } \d é um escape de regex, não de JSON. { "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }
{ "char": "\u12" } \u deve ser seguido por exatamente 4 dígitos hexadecimais. { "char": "\u0012" }
{ "emoji": "\u{1F600}" } JavaScript aceita isso em strings do código-fonte; JSON não. { "emoji": "😀" } ou { "emoji": "\uD83D\uDE00" }

Um detalhe incômodo merece um aviso próprio: \f é um escape JSON válido. Se um caminho Windows contém \file, um parser pode transformá-lo em um caractere de form feed seguido por ile. O parse pode ter sucesso enquanto o valor do caminho fica corrompido. É por isso que "reparar" strings de caminho às cegas é arriscado.

Causa 1: caminhos Windows copiados para dentro do JSON

Caminhos Windows parecem inofensivos porque humanos leem a barra invertida como separador de caminho:

{ "downloadDir": "C:\Users\Ada\Downloads" }

O JSON lê a barra invertida como início de uma sequência de escape. Ele vê \U e para, porque U maiúsculo não é um escape JSON.

Escreva barras invertidas duplas no JSON:

{
  "downloadDir": "C:\\Users\\Ada\\Downloads"
}

Ou use barras normais, se o programa que vai receber aceitá-las:

{
  "downloadDir": "C:/Users/Ada/Downloads"
}

Para arquivos de configuração, barras normais costumam causar menos enganos. Para valores exatos apenas de Windows, barras invertidas duplas são a representação JSON portátil.

Causa 2: misturar strings do código-fonte JavaScript com texto JSON

É aqui que muitos exemplos na web confundem as pessoas por acidente. Existem duas camadas:

  • A sintaxe das strings no código-fonte JavaScript
  • A sintaxe do texto JSON dentro daquela string JavaScript

Este código-fonte JavaScript é válido:

const raw = '{"path":"C:\\Users\\Ada"}';
JSON.parse(raw);

Mas o texto JSON que chega ao parser é:

{"path":"C:\\Users\\Ada"}

Se você quiser testar uma amostra de JSON quebrada em JavaScript sem que o próprio JavaScript consuma as barras invertidas primeiro, use String.raw:

const broken = String.raw`{"path":"C:\Users\Ada"}`;
JSON.parse(broken);

Isso lança Bad escaped character porque JSON.parse() recebe o texto JSON realmente quebrado.

Use este modelo mental ao ler stack traces: se o JSON veio de um arquivo .json, corpo HTTP, valor no localStorage ou string no banco de dados, corrija o texto JSON. Se o JSON está dentro de uma string do código-fonte JavaScript, talvez seja preciso um nível de escape para o JavaScript e outro nível para o JSON.

Causa 3: pegar escapes emprestados de outras linguagens

O JSON aceita \n e \t, mas não aceita muitos escapes que são normais em linguagens de programação:

{ "code": "\x1b[0m", "name": "O\'Brien" }

JSON válido:

{
  "code": "\u001b[0m",
  "name": "O'Brien"
}

Falsos amigos comuns:

Escape Válido em Correção em JSON
\x1b JavaScript, Python, vários shells \u001b
\' Strings entre aspas simples em JavaScript/Python Use ' sem barra invertida
\0 Atalho de NUL em JavaScript/Python \u0000
\v Tabulação vertical do JavaScript \u000b
\U0001F600 Escape Unicode do Python Emoji UTF-8 literal ou par substituto
\u{1F600} Escape de ponto de código Unicode do JavaScript Emoji UTF-8 literal ou par substituto

Se o produtor é o seu código, não traduza cada caso à mão. Construa um objeto normal e deixe o serializador JSON da linguagem gerar um JSON válido.

Causa 4: padrões de regex armazenados em config JSON

Regex tem sua própria linguagem de escape. Strings JSON têm outra linguagem de escape separada. A barra invertida da regex precisa sobreviver ao parsing do JSON antes de chegar ao motor de regex.

Configuração JSON quebrada:

{ "datePattern": "^\d{4}-\d{2}-\d{2}$" }

Configuração JSON válida:

{
  "datePattern": "^\\d{4}-\\d{2}-\\d{2}$"
}

Após o parsing do JSON, a aplicação vê esta string:

^\d{4}-\d{2}-\d{2}$

Só então ela deve virar uma expressão regular:

const config = JSON.parse('{"datePattern":"^\\\\d{4}-\\\\d{2}-\\\\d{2}$"}');
const re = new RegExp(config.datePattern);

A mesma regra vale para \s, \w, \b, grupos nomeados, exemplos de lookbehind e strings de substituição. Se a barra invertida é para um parser posterior, duplique-a no JSON.

Causa 5: escapes Unicode malformados

O escape Unicode do JSON tem largura fixa:

{ "char": "\u12" }

JSON válido:

{
  "char": "\u0012"
}

O u precisa ser minúsculo e ser seguido por exatamente quatro dígitos hexadecimais: 0-9, a-f ou A-F.

Estes não são escapes Unicode do JSON:

"\u{2028}"   // estilo do código-fonte JavaScript, não JSON
"\U00002028" // estilo Python, não JSON
"\u20G0"     // G não é dígito hexadecimal

Caracteres fora do Plano Multilíngue Básico, como muitos emojis e alguns símbolos matemáticos, podem ser armazenados literalmente em JSON UTF-8:

{
  "emoji": "😀"
}

Quando escapados, são representados como um par substituto UTF-16:

{
  "emoji": "\uD83D\uDE00"
}

Evite substitutos solitários como \uD83D sem o substituto baixo correspondente. Alguns parsers os aceitam como unidades de código, mas sistemas a jusante que exigem Unicode bem formado podem rejeitá-los.

Causa 6: strings JSON construídas à mão

Esta é a versão do bug que aparece em produção:

// Inseguro: userInput pode conter barras invertidas, aspas ou quebras de linha.
const payload = '{"message":"' + userInput + '"}';

Se userInput for C:\Users\Ada, o texto emitido é JSON inválido. Se contiver ", o JSON pode quebrar de outra forma. Se contiver uma quebra de linha bruta, você pode receber um bad control character em vez disso.

Use um serializador:

const payload = JSON.stringify({
  message: userInput,
  path: 'C:\\Users\\Ada\\file.json',
  code: '\x1b[32mOK\x1b[0m',
});

JSON.stringify() cuida do escape específico do JSON. O resultado é um texto JSON válido:

{
  "message": "...",
  "path": "C:\\Users\\Ada\\file.json",
  "code": "\u001b[32mOK\u001b[0m"
}

O mesmo princípio vale em outras linguagens:

import json

payload = json.dumps({
    "path": r"C:\Users\Ada\file.json",
    "pattern": r"^\d+$",
})

body, err := json.Marshal(map[string]string{
    "path": `C:\Users\Ada\file.json`,
    "pattern": `^\d+$`,
})

Se você está consertando um produtor, esta é a correção de verdade. Remendar JSON inválido lá na frente só esconde o lugar onde o texto ruim foi criado.

Como localizar o escape ruim

Para JSON colado, este pequeno helper facilita a leitura da área em torno do position do V8:

function showJsonParseContext(raw) {
  try {
    JSON.parse(raw);
    console.log('Valid JSON');
  } catch (error) {
    const message = String(error.message);
    const match = message.match(/position (\d+)/);

    if (!match) {
      console.log(message);
      return;
    }

    const pos = Number(match[1]);
    const start = Math.max(0, pos - 24);
    const end = Math.min(raw.length, pos + 24);
    const excerpt = raw.slice(start, end);

    console.log(message);
    console.log(JSON.stringify(excerpt));
    console.log(' '.repeat(pos - start) + '^');
  }
}

const raw = String.raw`{"path":"C:\Users\Ada\file.json"}`;
showJsonParseContext(raw);

O JSON.stringify(excerpt) é intencional. Ele mostra barras invertidas e caracteres de controle como escapes visíveis, que é exatamente o que você precisa quando o bug é espaço em branco invisível ou um escape excessivo.

Para erros no estilo do Firefox, com line e column, pule primeiro para essa linha e depois inspecione o literal de string nela. Se a coluna exata cair depois de uma barra invertida, leia também o caractere anterior.

Ferramenta de reparo ou rejeitar o payload?

Use uma ferramenta de reparo quando:

  • Você está limpando um trecho colado.
  • Você está depurando uma linha de log.
  • Você está revisando saída de um LLM.
  • Você consegue confirmar visualmente o valor reparado.
  • O valor não movimenta dinheiro, permissões, exclusões ou mudanças irreversíveis de estado.

Rejeite o payload e conserte o produtor quando:

  • O JSON veio de um contrato de API.
  • O valor afeta cobrança, permissões, segurança ou exclusão de dados.
  • O parser teve que adivinhar entre múltiplos significados possíveis.
  • Um caminho, regex ou sequência de escape poderia ser válido mas semanticamente errado.

Por exemplo, reparar C:\Users\Ada\file.json não é apenas uma operação de sintaxe. \f em \file é um escape válido, então uma ferramenta pode analisar um caractere de form feed em vez de preservar a barra invertida. Um humano ou o código do produtor precisa decidir qual é o caminho pretendido.

A ferramenta JSON Fix deste site é melhor usada como um assistente de depuração local no navegador: cole o texto, inspecione a saída e valide o JSON reparado. Ela não deve ser a camada de ingestão silenciosa para payloads de produção malformados.

Como desescapar JSON com segurança

Às vezes as barras invertidas não são ruins; o JSON está codificado duas vezes. Você pode ver isso em logs:

{\"name\":\"Ada\",\"path\":\"C:\\\\Users\\\\Ada\"}

Não rode um replace(/\\/g, '') genérico. Isso destrói escapes reais.

Analise uma camada JSON válida por vez:

// O valor externo é uma string JSON que contém texto JSON.
const wrapped = '"{\\"name\\":\\"Ada\\",\\"path\\":\\"C:\\\\\\\\Users\\\\\\\\Ada\\"}"';

const once = JSON.parse(wrapped);
// once é: {"name":"Ada","path":"C:\\Users\\Ada"}

const data = JSON.parse(once);
// data é: { name: "Ada", path: "C:\\Users\\Ada" }

Se o primeiro parse falhar com Bad escaped character, a entrada não está apenas codificada. É texto JSON inválido e precisa de um reparo direcionado.

Checklist de prevenção

  • Nunca concatene strings de usuário dentro de JSON.
  • Use JSON.stringify(), json.dumps(), json.Marshal() ou o serializador JSON da sua plataforma.
  • Armazene padrões de regex em JSON com barras invertidas duplas.
  • Prefira barras normais para caminhos quando o consumidor aceitar.
  • Coloque entre aspas e teste exemplos copiados de logs, shells e documentação.
  • Valide arquivos .json gerados em CI com um parser de verdade.
  • Registre uma pré-visualização segura ao redor da posição do parser, em vez de logar o payload inteiro.
  • Trate reparo automático como fluxo de desenvolvimento, não como contrato de produção.

Perguntas frequentes

O que significa "Bad escaped character in JSON"?

Uma barra invertida dentro de uma string JSON é seguida por um caractere que o JSON não permite depois de \. Escapes válidos são ", \, /, b, f, n, r, t e uXXXX.

Como corrijo um caminho Windows em JSON?

Escreva cada barra invertida do caminho como \\, por exemplo C:\\Users\\Ada\\file.json. Se o programa que vai receber aceitar barras normais, C:/Users/Ada/file.json é JSON válido e mais fácil de ler.

Por que minha regex funciona em JavaScript mas falha em JSON?

O parser JSON vê a string antes do motor de regex. Um escape de regex como \d precisa ser escrito como \\d em JSON para que a string analisada ainda contenha \d.

\x1b é JSON válido?

Não. \xNN é comum em JavaScript, Python e exemplos de shell, mas o JSON não suporta. Use \u001b para o caractere ESC do ANSI, ou remova os códigos de cor ANSI antes de serializar os logs.

Isso é o mesmo que "Bad control character"?

Não. "Bad escaped character" significa que o caractere depois de uma barra invertida é inválido. "Bad control character" significa que um byte de controle bruto, como uma quebra de linha, tab, NUL ou byte ESC literal, aparece dentro de uma string JSON.

As ferramentas de reparo JSON conseguem corrigir escapes ruins automaticamente?

Às vezes, para trechos colados em que o valor pretendido é óbvio. Não faça auto-reparo silencioso em payloads de API, dados sensíveis à segurança, pagamentos, permissões, exclusões ou valores em que \f, \n ou \t possam ser válidos mas não intencionais.

Como faço para desescapar JSON?

Analise uma camada por vez com JSON.parse(). Um valor codificado duas vezes vira uma string JSON normal após o primeiro parse e um objeto ou array de verdade após o segundo. Evite remover barras invertidas com regex, porque isso corrompe escapes válidos.

Como evito esse erro no código-fonte?

Construa valores nativos e serialize-os com JSON.stringify() ou o serializador equivalente na sua linguagem. Não monte JSON com concatenação de strings.

Corrija agora

Fontes

Última revisão em julho de 2026.