SQL Erros Comuns

Todo mundo erra SQL, todo dia: uma letra trocada no nome da tabela, uma vírgula sobrando, aspas do tipo errado. O SQLite sempre avisa, mas avisa em inglês e com poucas palavras. Esta página é um dicionário dessas mensagens: cada uma aparece exatamente como sai no editor do guia e no terminal do sqlite3, com a tradução, a causa mais comum, o conserto e a aula onde o assunto é explicado.

Como ler uma mensagem de erro

O mesmo erro aparece um pouco diferente em cada lugar. No editor do guia, a mensagem sai crua, do jeito que o SQLite a escreveu:

SELECT nomee FROM clientes;

No terminal do SQLite, o programa sqlite3 acrescenta um prefixo e, muitas vezes, uma seta mostrando onde ele se perdeu:

$ sqlite3 loja.db
SQLite version 3.50.4 2025-07-30 19:33:53
Enter ".help" for usage hints.
sqlite> SELECT nomee FROM clientes;
Parse error: no such column: nomee
  SELECT nomee FROM clientes;
         ^--- error here

Parse error:

"Erro de análise". O SQLite nem começou a rodar: o problema foi achado ao ler o comando (nome que não existe, sintaxe errada). Nada no banco mudou.

no such column: nomee

A mensagem em si: "não existe a coluna nomee". É o mesmo texto que o editor mostra.

SELECT nomee FROM clientes;

O terminal repete o seu comando…

^--- error here

…e aponta o lugar do erro ("o erro está aqui"). Quando o ponto fica no fim da linha, a seta vira error here ---^, com o ^ à direita.

Os prefixos que você vai encontrar no terminal:

1. Nomes que não existem

O grupo mais comum de todos: o SQLite não achou a tabela, a coluna ou a função com o nome que você escreveu. Quase sempre é uma letra trocada, um plural esquecido ou um apelido mal usado. Os nomes das tabelas do guia estão todos no plural: clientes, produtos, pedidos, itens_pedido…

Veja o caso do apelido rodando de verdade:

SELECT c.nome
FROM clientes c
WHERE clientes.id = 1;

E o do nome ambíguo, que só aparece quando há duas tabelas:

SELECT id, nome
FROM clientes
JOIN pedidos ON pedidos.cliente_id = clientes.id;

No terminal da Ana, a seta mostra exatamente qual id está ambíguo: o primeiro, depois do SELECT.

sqlite> SELECT id, nome FROM clientes JOIN pedidos ON pedidos.cliente_id = clientes.id;
Parse error: ambiguous column name: id
  SELECT id, nome FROM clientes JOIN pedidos ON pedidos.cliente_id = clientes.id
         ^--- error here

2. Erros de escrita (sintaxe)

Aqui o SQLite não conseguiu nem entender a frase. A mensagem típica é near "X": syntax error, "perto de X: erro de sintaxe". O X é a palavra onde ele percebeu o erro, que nem sempre é onde o erro está: muitas vezes o problema é a palavra logo antes.

SELECT nome, email
FROM clientes
WHERE nome = "Ana Carvalho Lima";

sqlite> SELECT nome FROM clientes WHERE nome = "Ana Carvalho Lima";
Ana Carvalho Lima
sqlite> 

O comando que não termina, no terminal

No editor, um parêntese aberto sem ; dá incomplete input. No prompt do sqlite3, ninguém reclama: o terminal acha que você ainda vai continuar o comando e muda o prompt para ...> (continuação). Se houver um parêntese aberto, o prompt mostra quantos: (x1...>.

sqlite> SELECT nome FROM clientes WHERE (id = 1
(x1...> ;
Parse error: near ";": syntax error
  SELECT nome FROM clientes WHERE (id = 1 ;
                            error here ---^

Quando o ; finalmente chega, o SQLite vê o parêntese que não fechou e reclama. Se o terminal "travou" mostrando ...>, quase sempre falta um ; (ou uma aspa, ou um parêntese): digite o que falta e Enter. Já com o SQL na linha de comando, a mensagem é a mesma do editor:

$ sqlite3 loja.db "SELECT nome FROM clientes WHERE (id = 1"
Error: in prepare, incomplete input
$ sqlite3 loja.db "SELECT nome FROM clientes WHERE nome = 'Ana"
Error: in prepare, unrecognized token: "'Ana"
  SELECT nome FROM clientes WHERE nome = 'Ana
                           error here ---^

SELECT nome, email
FROM cliente
WHERE nome = "Ana Carvalho Lima";

SELECT nome, email
FROM clientes
WHERE nome = 'Ana Carvalho Lima';

3. Regras da tabela quebradas (constraint failed)

Estes erros aparecem quando o comando está bem escrito, mas os dados quebram uma regra que a tabela tem. Constraint quer dizer "restrição", e failed, "falhou": a regra não foi cumprida, e o comando inteiro foi recusado. No terminal, eles vêm como Runtime error com o código (19).

Dois exemplos rodando de verdade. A categoria 1 (Papelaria) já existe:

INSERT INTO categorias (id, nome, descricao)
VALUES (1, 'Pet Shop', 'Ração e brinquedos para bichos');

E não existe cliente 999 para receber um pedido:

INSERT INTO pedidos (cliente_id, funcionario_id, data, frete)
VALUES (999, 2, '2026-10-18', 0);

No terminal, os mesmos erros saem com o prefixo Runtime error e o código (19) no fim:

sqlite> INSERT INTO clientes (id, nome) VALUES (1, 'Teste');
Runtime error: UNIQUE constraint failed: clientes.id (19)
sqlite> INSERT INTO categorias (nome) VALUES (NULL);
Runtime error: NOT NULL constraint failed: categorias.nome (19)
sqlite> PRAGMA foreign_keys = ON;
sqlite> INSERT INTO pedidos (cliente_id, funcionario_id, data, frete) VALUES (999, 2, '2026-10-18', 0);
Runtime error: FOREIGN KEY constraint failed (19)
sqlite> INSERT INTO clientes (id, nome) VALUES ('abc', 'Teste');
Runtime error: datatype mismatch (20)

sqlite> PRAGMA foreign_keys;
0

INSERT INTO categorias (id, nome, descricao)
VALUES (1, 'Pet Shop', 'Ração e brinquedos para bichos');

INSERT INTO categorias (nome, descricao)
VALUES ('Pet Shop', 'Ração e brinquedos para bichos');

4. Agregar e agrupar

As funções agregadas (COUNT, SUM, AVG…) e as funções de janela só podem aparecer em certos lugares da consulta. Usá-las no lugar errado dá um destes erros.

SELECT nome
FROM clientes
WHERE SUM(id) > 10;

5. Contas de colunas que não fecham

Erros em que dois lados precisam ter a mesma quantidade de coisas e não têm: as colunas de um UNION, os valores de um INSERT, as colunas de uma subconsulta.

SELECT nome, cidade FROM clientes
UNION
SELECT nome FROM fornecedores;

6. Transações

7. No terminal: arquivo, trava e permissão

Estes só aparecem no programa sqlite3, com um banco de verdade num arquivo. O editor do guia usa um banco na memória, só seu, e nunca dá esses erros.

A Ana reproduziu cada um. Primeiro, o banco trancado: um sqlite3 rodando em segundo plano (o & no fim) abre uma transação exclusiva e a segura por 3 segundos; enquanto isso, outro tenta mudar o estoque:

$ (echo 'BEGIN EXCLUSIVE;'; sleep 3; echo 'COMMIT;') | sqlite3 loja.db &
[1] 11
$ sleep 1
$ sqlite3 loja.db "UPDATE produtos SET estoque = estoque + 1 WHERE id = 1;"
Error: in prepare, database is locked (5)

Depois, o banco somente leitura, das duas formas: com a opção -readonly e com o arquivo sem permissão de escrita (chmod 444):

$ sqlite3 -readonly loja.db "DELETE FROM clientes WHERE id = 30;"
Error: stepping, attempt to write a readonly database (8)
$ cp loja.db copia.db
$ chmod 444 copia.db
$ sqlite3 copia.db "DELETE FROM clientes WHERE id = 30;"
Error: stepping, attempt to write a readonly database (8)

E o arquivo com nome errado, que vira um banco novo e vazio:

$ sqlite3 nada.db "SELECT * FROM clientes;"
Error: in prepare, no such table: clientes
$ ls nada.db
nada.db                « o sqlite3 criou o arquivo
$ rm -f nada.db

Por fim, os comandos de ponto digitados errado no prompt:

sqlite> .tabels
Error: unknown command or invalid arguments:  "tabels". Enter ".help" for help
sqlite> tables
   ...> ;
Parse error: near "tables": syntax error
  tables ;
  ^--- error here

8. Os erros que não dão erro

Os piores erros são os que o SQLite não acusa: a consulta roda, mostra um resultado, e o resultado está errado. Estes enganam todo iniciante pelo menos uma vez:

Veja três deles de uma vez, rodando de verdade:

SELECT 7/2, 7/2.0, 1/0, 'abc' + 1;
SELECT COUNT(*) AS com_igual FROM clientes WHERE email = NULL;
SELECT COUNT(*) AS com_is FROM clientes WHERE email IS NULL;

Os códigos numéricos

O número entre parênteses no fim das mensagens do terminal é o código de resultado do SQLite. Programas (em PHP, Python…) costumam olhar esse número em vez do texto. Os que aparecem nesta página:

Exercícios

Resumo

• No editor, a mensagem sai crua (no such table: cliente). No terminal, vem com prefixo: Parse error (o comando nem rodou), Runtime error … (19) (parou no meio), ou Error: in prepare / Error: stepping com o SQL na linha de comando.
• no such table, no such column, ambiguous column name: confira o nome (as tabelas do guia estão no plural) e, num JOIN, diga de qual tabela é a coluna.
• near "X": syntax error: o erro está em X ou logo antes dele. Vírgula sobrando, palavra errada, partes fora de ordem.
• Texto vai entre aspas simples. Aspas duplas são para nomes, e dão no such column: "…".
• … constraint failed: o comando estava certo, os dados quebraram uma regra da tabela (UNIQUE, NOT NULL, FOREIGN KEY, CHECK). No sqlite3, a chave estrangeira só é checada com PRAGMA foreign_keys = ON.
• Agregada no WHERE dá misuse of aggregate: filtre grupos com HAVING.
• Cuidado com o que não dá erro: = NULL, 7/2, 1/0, 'abc' + 1 e o UPDATE sem WHERE.