ORA-06502: Guia definitivo para entender, diagnosticar e corrigir o erro ORA-06502 no Oracle

18Jan

ORA-06502: Guia definitivo para entender, diagnosticar e corrigir o erro ORA-06502 no Oracle

O que é ORA-06502 e por que ele ocorre

O erro ORA-06502, na forma completa “ORA-06502: PL/SQL: numeric or value error”, aparece quando uma operação PL/SQL tenta atribuir, converter ou armazenar um valor que não cabe no tipo de dados ou tamanho disponível. Em termos simples, é uma sinalização de que houve estouro de precisão, escala ou tamanho, ou ainda uma conversão inválida entre tipos. Este erro pode surgir tanto em blocos PL/SQL puros quanto em chamadas a procedures, funções ou pacotes que manipulam dados, variáveis, arrays (coleções) e buffers de saída.

ORA-06502 versus a pilha de erros: como interpretar o contexto

Ao observar o ORA-06502, é comum aparecer também uma linha de referência, por exemplo “PL/SQL: numeric or value error” seguido da linha onde a exceção foi levantada. Em ambientes com tracing ligado, você pode ver um stack trace com ORA-06502 envolvido. Compreender o contexto é crucial: pode ser uma atribuição direta a uma variável, uma conversão de tipos, ou o resultado de uma operação aritmética que excede a capacidade de armazenamento definida pela declaração de variável ou por uma coluna de tabela.

Causas comuns do ORA-06502

Conversões de tipos inadequadas: tentar atribuir um valor de tipo diferente sem conversão explícita adequada, por exemplo atribuir VARCHAR2 a NUMBER sem conversão.
Exceder a precisão ou a escala de um NUMBER: números com mais dígitos antes ou depois da vírgula do que o permitido pela definição NUMBER(precision, scale).
Excesso de tamanho em VARCHAR2: atribuir mais caracteres a uma variável VARCHAR2 ou a uma coluna com definição de tamanho menor.
Overflow de valor em data/hora: tentar armazenar um valor de data fora do intervalo permitido ou de forma incompatível com a declaração.
Buffer ou espaço insuficiente: em chamadas a DBMS_OUTPUT ou em buffers de saída/descritores de cursor, quando a saída excede o espaço reservado.
Trabalhos com coleções (TABLE, VARRAY) sem respeitar limites de índices ou tamanho de elementos.
Operações com tipos compostos (RECORDs) mal dimensionados ou com atribuições que não respeitam os campos.

Cenários práticos que costumam gerar ORA-06502

Exemplo 1: atribuição que excede a precisão de NUMBER

DECLARE
  v_val NUMBER(5,2);
BEGIN
  v_val := 1234.56; -- excede NUMBER(5,2) que permite até 999.99
END;

Neste caso, a atribuição provoca overflow de valor, levando ao ORA-06502. A solução é ajustar a declaração NUMBER(5,2) para comportar o valor esperado ou adaptar o valor a ser atribuído.

Exemplo 2: string para number sem conversão explícita

DECLARE
  v_num NUMBER;
  v_str VARCHAR2(20) := 'ABC123';
BEGIN
  v_num := v_str; -- erro: conversão implícita falha
END;

Converte-se incorretamente uma string não numérica para número. Em muitos casos isso gera ORA-01722, mas em cenários específicos com regras de conversão ou NLS, o ORA-06502 pode aparecer ao tentar armazenar o resultado da conversão em uma variável com restrições de tamanho ou formato.

Exemplo 3: buffer de saída com DBMS_OUTPUT

DECLARE
  v_buf VARCHAR2(2000);
  v_msg VARCHAR2(4000) := RPAD('X', 4000, 'X'); -- excede o buffer de saída
BEGIN
  DBMS_OUTPUT.PUT_LINE(v_msg);
END;

O erro pode ocorrer quando o tamanho da saída excede o buffer configurado pelo DBMS_OUTPUT.ENABLE. Ajustar o tamanho do buffer ou dividir a saída é a abordagem recomendada.

Exemplo 4: uso de VARCHAR2 em tabelas com limites menores

CREATE TABLE clientes (
  id NUMBER,
  cpf VARCHAR2(11)
);

DECLARE
  v_cpf VARCHAR2(14) := '123.456.789-00'; -- 14 caracteres, mas a coluna suporta 11
BEGIN
  INSERT INTO clientes (id, cpf) VALUES (1, v_cpf);
END;

A tentativa de armazenar mais caracteres do que o definido para a coluna resulta em ORA-06502 em alguns cenários de cast/driver de banco ao retornar resultados ou em blocos com validação de tamanho.

Como diagnosticar ORA-06502 de forma eficaz

1) Reproduzir com o mínimo possível de código

Isolar o trecho que dispara o erro facilita a identificação da variável ou do tipo envolvido. Tente reduzir o bloco a um exemplo mínimo que cause o erro, sem dependências externas.

2) Verificar declarações de variáveis e tipos

Compare os tipos de cada variável com os valores atribuídos a elas. Verifique se há consistência entre VARCHAR2, NUMBER, DATE, e se a declaração suporta a magnitude esperada.

3) Utilizar SQLCODE e SQLERRM

Em tratativas de exceções, registre o código de erro e a mensagem: SQLCODE e SQLERRM. Em muitos casos, a mensagem fornecida pelo ORA-06502 acompanha informações úteis sobre a linha e o objeto envolvido.

4) Conferir operações com coleções e buffers

Para coleções, confirme índices válidos e se os elementos respeitam a dimensão máxima. Para DBMS_OUTPUT, confirme o buffer com DBMS_OUTPUT.ENABLE(buffer_size => 1000000) ou outro valor adequado.

5) Analisar dados de entrada e regras de negócio

Valide entradas de usuários, integrações externas e regras de negócio que possam gerar valores fora do esperado antes de atribuir a variáveis ou persistir em tabelas.

Como corrigir ORA-06502: estratégias práticas

Validação de dados antes de atribuições

Antes de atribuir valores a variáveis, faça validações explícitas: tamanho, formato, faixa de números, e consistência de datas. Use funções como TO_NUMBER com máscara explícita, TO_CHAR para formatação, e checagens condicionais para prevenir estouros.

Uso correto de castings e conversões

Quando for necessário converter tipos, utilize conversões explícitas com formatos apropriados, por exemplo:

DECLARE
  v_num VARCHAR2(20) := '1234.56';
  v_val NUMBER(8,2);
BEGIN
  v_val := TO_NUMBER(v_num, '999999.99');
END;

Converta com máscara que reflita o valor esperado e trate exceções de conversão para evitar surpresas pelo locale (NLS).

Ajuste de precisão, escala e tamanho

Se a definição de NUMBER, VARCHAR2 ou DATE não atende às necessidades, ajuste a definição. Por exemplo, aumentar NUMBER(8,2) para comportar valores com mais dígitos ou ampliar VARCHAR2(n) para armazenar strings mais longas.

Tratar exceções com clareza

Use blocos de exceção específicos para capturar ORA-06502 e agir com mensagens úteis para o usuário final ou log para auditoria. Evite capturar tudo com WHEN OTHERS THEN sem tratamento adequado.

BEGIN
  -- código que pode gerar ORA-06502
EXCEPTION
  WHEN VALUE_ERROR THEN
    DBMS_OUTPUT.PUT_LINE('Erro de valor: verifique tipos e tamanhos.');
  WHEN OTHERS THEN
    DBMS_OUTPUT.PUT_LINE('Outro erro: ' || SQLCODE || ' - ' || SQLERRM);
END;

Uso adequado de records e %TYPE

Defina variáveis com o uso de %TYPE para manter consistência com as tabelas, evitando discrepâncias entre tamanho e tipo que possam levar a ORA-06502.

Boas práticas para evitar ORA-06502 no dia a dia

Validação de entrada de dados

Implemente validação de lado do servidor para garantir que entradas de usuário estejam dentro dos limites permitidos antes da persistência. Realize checagens de formato, tamanho e consistência entre campos relacionados.

Definição cuidadosa de esquemas

Projete esquemas com margens de segurança para tipos de dados. Evite usar precisão mínima onde existem margens de crescimento previsíveis. Considere padrões de dados, especialmente em aplicações que recebem dados de fronteiras geográficas ou de integrações externas.

Testes com casos de borda

Inclua testes que cobrem casos de máxima/mínima magnitude, strings longas, datas próximas de limites e cenários de produção com volumes altos de dados para capturar ORA-06502 antes de ir para produção.

Observabilidade e logs eficientes

Registre informações relevantes quando ocorrer ORA-06502: quais variáveis estavam envolvidas, qual a origem da atribuição, e quais são os limites que foram extrapolados. Isso facilita a correção sem depender de reprodução única em produção.

Ferramentas e recursos úteis para trabalhar com ORA-06502

DBMS_OUTPUT e buffer management

Configurar o buffer com DBMS_OUTPUT.ENABLE(buffer_size => 1000000) ajuda a captar mensagens de depuração sem perda de informações. Em ambientes com saída extensa, dividir mensagens em blocos menores é recomendado.

Uso de SQL Developer, DataGrip e IDEs

Ferramentas modernas permitem traçar exceções com highlighting, destacar a linha exata onde ORA-06502 ocorreu e fornecer sugestões rápidas de correção, além de integração com testes unitários de PL/SQL.

Trace e SQL tracing

Para cenários mais complexos, ative tracing para entender como os dados fluem pelas camadas. Observando o plano de execução e os valores de variáveis no momento da exceção facilita o diagnóstico de gargalos que levam ao ORA-06502.

Recursos oficiais e documentação

A documentação da Oracle descreve as mensagens de erro, cenários de ocorrência e melhores práticas para escrever código PL/SQL robusto, permitindo aos times de desenvolvimento alinhar convenções de tratamento de exceções com padrões corporativos.

Exemplos de código úteis para evitar ORA-06502

Exemplo A: validação pré-atribuição com NUMBER

DECLARE
  v_sal NUMBER(10,2);
  v_input VARCHAR2(20) := '12345678.90';
BEGIN
  IF REGEXP_LIKE(v_input, '^\d+(\.\d{1,2})?$') THEN
    v_sal := TO_NUMBER(v_input);
  ELSE
    RAISE_APPLICATION_ERROR(-20001, 'Entrada inválida para valor monetário');
  END IF;
END;

Exemplo B: ajuste de tamanho de VARCHAR2

DECLARE
  v_nome VARCHAR2(50);
BEGIN
  v_nome := 'Nome extremamente longo que pode exceder o limite';
  IF LENGTH(v_nome) > 50 THEN
    v_nome := SUBSTR(v_nome, 1, 50);
  END IF;
END;

Exemplo C: tratamento específico de retorno de funções

CREATE OR REPLACE FUNCTION get_limite(p_id NUMBER) RETURN NUMBER IS
  v_limite NUMBER(8,2);
BEGIN
  SELECT limite INTO v_limite FROM itens WHERE id = p_id;
  RETURN v_limite;
EXCEPTION
  WHEN NO_DATA_FOUND THEN
    RETURN 0;
  WHEN VALUE_ERROR THEN
    RETURN 99999; -- valor de falha controlada
END;

Conclusão: ORA-06502 como alarme de qualidade de código

ORA-06502 não é apenas uma mensagem de erro para corrigir rapidamente; é um indicador valioso de que a aplicação pode não estar validando adequadamente dados, não respeitando limites de tipos ou dimensionamentos de memória. Adotar práticas preventivas, validação de dados na origem, uso consciente de tipos de dados, tratamento de exceções específico e logs claros reduz significativamente a ocorrência desse erro em ambientes de produção. Com uma abordagem estruturada, você transforma o ORA-06502 de um obstáculo técnico em uma oportunidade de melhorar a robustez, a confiabilidade e a qualidade de suas aplicações Oracle.