Invalid input syntax for type json no PostgreSQL: como achar a causa real
Uma medição detalhada mostra que o erro mais comum de colunas json e jsonb no PostgreSQL esconde comportamentos diferentes entre drivers, versões e até entre json e jsonb na mesma instância.

- Leitura
- 7 min
- Tabelas
- 1
- Código
- 2
- Fontes
- 1
Uma medição detalhada mostra que o erro mais comum de colunas json e jsonb no PostgreSQL↳PostgreSQL11 conteúdosPostgreSQL via SSL com GolangData · abr 20195 itens legais sobre data types do PostgreSQLData · mar 20195 serviços gratuitos na cloud para bancos de dados PostgresData · fev 2025Ver tudo em Data → esconde comportamentos diferentes entre drivers, versões e até entre json e jsonb na mesma instância.
O que a mensagem realmente diz
O erro invalid input syntax for type json aparece sempre que um texto é entregue a uma coluna json ou jsonb e esse texto não é JSON válido para o parser do PostgreSQL. Um levantamento publicado no Planet PostgreSQL testou 38 entradas diferentes contra as versões 16.15, 17.11 e 18.6 e chegou a um resultado incômodo: a mensagem, o SQLSTATE (22P02, invalid_text_representation) e o DETAIL são idênticos nas três versões. Só a linha LOCATION muda.
Isso significa que a mensagem não informa tabela, coluna ou linha. Um cast, um INSERT com parâmetro ou um ALTER mostram apenas o início do texto problemático. Só o COPY adiciona essa informação ao CONTEXT. Na prática, quem depura esse erro em produção está lendo um fragmento de string, não um ponteiro para o dado.
O campo DETAIL aponta o primeiro token que o parser não aceitou, o que ajuda a entender o tipo de problema, mas não a localização. Um str() de dicionário em Python↳Python56 conteúdosVSCode + Python + Alexa: Desenvolva e teste skills para alexa localmente com pythonDev (Back & Front) · out 2025Dominando decoradores em Python: um guia completo com exemplosDev (Back & Front) · jan 2025Desenvolvimento de software: diferenças entre Python, JavaScript e JavaGestão Dev & TI · nov 2024Ver tudo em Dev (Back & Front) →, por exemplo, produz Token "'" is invalid., porque o parser JSON não aceita aspas simples. Um array do PostgreSQL como {"a","b"} falha com Expected ":", but found ","., porque o parser interpreta as chaves como início de objeto.
Nem todo erro de dado dispara o erro
A medição separa claramente o que falha do que passa despercebido, e a segunda lista é a mais perigosa para quem desenha schema:
NaN,undefined,True(maiúsculo) e chaves sem aspas falham com22P02emjsonejsonb.\u0000dentro de uma string é aceito porjson, mas rejeitado porjsonbcom um código diferente,22P05(untranslatable_character).\ud800, um surrogate sem par, segue a mesma regra: passa emjson, falha emjsonb.- Um documento JSON codificado duas vezes, como
"{\"a\": 1}", é aceito pelos dois tipos como uma string JSON válida, não como objeto. - Chaves duplicadas, como
{"a": 1, "a": 2}, são aceitas porjsonb, que mantém só o último valor.
O ponto de modelagem aqui é direto: json verifica "apenas correção sintática", enquanto jsonb valida escapes Unicode de verdade, segundo a própria documentação. Uma coluna json pode guardar anos de linhas com \u0000 sem jamais reclamar, até o dia em que alguém tenta migrar para jsonb ou simplesmente lê o valor com ->>, que já falha com 22P05 mesmo em coluna json.
O driver é cúmplice do erro
Parte relevante dos casos que a medição reproduziu não vem do SQL, vem do driver. Com node-postgres 8.23.1, um array JavaScript como [1, 2] enviado como parâmetro $1 para uma coluna jsonb não vira JSON: vira um literal de array do PostgreSQL, {"1","2"}. O INSERT falha com 22P02 e Expected ":", but found ","., porque o parser lê as chaves como objeto.
O caso mais traiçoeiro é o array vazio. [] sai como {}, que é JSON válido e é armazenado sem erro como objeto vazio, tanto em json quanto em jsonb. Código que espera ler de volta um array recebe {}. A correção, segundo a medição, é serializar o array você mesmo: JSON.stringify([1, 2]) é armazenado corretamente como [1,2] nos dois tipos de coluna e também através de bibliotecas como Kysely.
Com psycopg 3.3.8 o comportamento depende do conteúdo da lista Python. [1, 2] falha com 42804 porque o adaptador tipa o valor como smallint[]; ['a', 'b'] falha com 22P02; e [] vira {} silenciosamente, como no node-postgres. Passar um dict sem wrapper nem chega a gerar SQLSTATE, é erro do cliente. A recomendação da medição é usar sempre Jsonb(...) (ou Json(...) para coluna json) e nunca montar o texto com str(). Mesmo assim, o wrapper não protege contra NaN: um float('nan') dentro do dicionário chega ao PostgreSQL como o token NaN e derruba o INSERT.
Antes do ALTER, ache as linhas ruins
Transformar uma coluna de text para jsonb com ALTER COLUMN ... TYPE jsonb USING payload::jsonb para na primeira linha inválida e desfaz tudo, inclusive um UPDATE anterior na mesma transação. Em vez de descobrir isso em produção, a medição recomenda consultar antes com pg_input_is_valid e pg_input_error_info:
select l.id, e.sql_error_code, e.message, e.detail
from legacy l, pg_input_error_info(l.payload, 'jsonb') e
where e.sql_error_code is not null;Essa consulta não para no primeiro erro: ela lista todas as linhas problemáticas de uma vez, com o código SQLSTATE e o DETAIL de cada uma. É a diferença entre corrigir uma linha por ALTER falhado e corrigir o lote inteiro numa única rodada de análise.
Um cuidado importante: o predicado IS JSON do padrão SQL parece equivalente a pg_input_is_valid(txt, 'json'), e de fato é, mas diverge de pg_input_is_valid(txt, 'jsonb') justamente nos três casos que importam para uma migração, \u0000, {"a": "x\u0000y"} e \ud800. Validar com IS JSON antes de um ALTER para jsonb deixa essas linhas passarem no check e travarem o ALTER de qualquer forma.
O custo de checar antes é pequeno. Num teste com um milhão de linhas (cerca de 110 MB, 10 mil linhas inválidas), pg_input_is_valid(payload, 'jsonb') levou entre 301 e 311 ms nas três versões testadas; IS JSON foi cerca de 2,6 vezes mais rápido, mas com a ressalva de dar a resposta errada para jsonb nos três casos citados.
O preço de um ALTER que falha de verdade
Os números da medição em PostgreSQL 18.6, numa tabela de cerca de um milhão de linhas, mostram por que vale a pena validar antes:
| Cenário | Tempo |
|---|---|
| Falha logo na linha 100 (segunda página) | 1,5 ms |
| Falha perto do fim (linha 990.000) | 1.619 ms |
| Sucesso, 990.000 linhas válidas, cast direto | 1.800 ms |
Sucesso, mesmo lote, com pg_input_is_valid | 2.643 ms |
Uma falha perto do fim da tabela custa quase tanto quanto uma reescrita completa bem-sucedida, porque o PostgreSQL já processou quase todas as linhas antes de desistir. A validação prévia encarece o ALTER bem-sucedido em 40 a 50%, porque cada linha é lida duas vezes, uma para checar e outra para converter. É uma troca explícita: mais tempo de execução por uma migração que não some no meio do caminho.
A armadilha do PostgreSQL 18 na função de proteção
A forma mais comum de evitar o erro é envolver o cast num CASE: case when pg_input_is_valid(t, 'jsonb') then t::jsonb end. A medição testou quatro variantes dessa ideia e descobriu que, a partir do PostgreSQL 18, uma delas ficou instável: a função SQL marcada como immutable.
O motivo é uma mudança no cache de planos, listada nas notas de release do PostgreSQL 18 sob otimizador, não sob incompatibilidades: a melhoria no cache de planos de funções SQL permite que o planejador trate o argumento como constante dentro de um plano customizado, e nesse caso ele avalia o cast immutable antes de o CASE conseguir pular a linha ruim. Isso bate com a regra documentada de que as cinco primeiras execuções de uma função usam plano customizado; a partir da sexta, plano genérico, sem o problema.
A variante que se manteve confiável nas três versões testadas foi a função em PL/pgSQL:
create or replace function try_jsonb(t text) returns jsonb
language plpgsql immutable
as $$
begin
if pg_input_is_valid(t, 'jsonb') then return t::jsonb; end if;
return null;
end $$;Usada num ALTER COLUMN payload TYPE jsonb USING try_jsonb(payload), essa função funcionou em todas as três versões testadas. É mais lenta, cerca de 3,2 segundos contra 2,6 do CASE direto no mesmo lote de 990 mil linhas válidas, mas não depende de quantas vezes a sessão já chamou a função antes.
O que fica para quem decide a migração
Transformar linha inválida em NULL é uma decisão sobre os dados, não uma correção. A medição recomenda listar primeiro com pg_input_error_info e decidir por tipo de erro: um repr de dicionário Python costuma ter conserto automático, uma string vazia provavelmente deveria virar NULL mesmo, e um \u0000 exige escolher o que aquele caractere deveria ter sido. Rodar o ALTER direto numa tabela grande sem esse diagnóstico prévio é apostar que nenhuma linha vai custar o preço de uma reescrita completa no meio do caminho.
Fonte: Planet PostgreSQL
Highlights
- Erro invalid input syntax para json e jsonb não informa tabela, coluna ou linha problemática, só o primeiro token inválido
- node-postgres 8.23.1 converte array vazio [] para {}, armazenado como objeto válido sem erro
- Validar com pg_input_is_valid custa 40-50% a mais mas detecta 10 mil linhas ruins em 310 ms num milhão de registros
- PostgreSQL 18 mudou cache de planos: função SQL immutable no CASE avalia cast antes e ignora validação
- json e jsonb divergem em 3 casos: \u0000, strings com \u0000 e surrogate \ud800 passam em json, falham em jsonb
Este artigo foi escrito por Roberto Diniz, colunista de banco de dados. Conteúdo produzido por agente de IA da redação iMasters, sob revisão editorial humana. Saiba como produzimos no expediente.
OpenEverest expõe failover automático de cluster MySQL Galera sem perda de dados
A Percona publicou um teste ao vivo de failover num cluster Percona XtraDB Cluster rodando em Kubernetes via OpenEverest, derrubando o nó escritor em produção simulada e acompanhando a reconfiguração automática pelo HAProxy.













