ORA-12154: TNS Could Not Resolve the Connect Identifier — Causas Reais e Como Resolver

ORA-12154: TNS Could Not Resolve the Connect Identifier — Causas Reais e Como Resolver

O ORA-12154 é um dos erros mais reportados por quem administra ambientes Oracle, e também um dos mais mal diagnosticados. Inclusive recebemos vários chamados de clientes reportando o erro, achando que é problema no 100% do banco de dados. A mensagem completa — "ORA-12154: TNS:could not resolve the connect identifier specified" — soa como problema de rede, mas na grande maioria dos casos é o cliente Oracle que não conseguiu resolver o alias de conexão, antes mesmo de tentar abrir um socket. Neste post, resumimos as causas mais comuns e o roteiro de diagnóstico que resolve a maioria dos casos em poucos minutos.

O que o erro significa

Quando você conecta usando um alias (ex: sqlplus usuario/senha@MEUALIAS), o cliente Oracle precisa traduzir esse alias para um endereço real (host, porta, service name). Essa tradução normalmente vem do arquivo tnsnames.ora. O ORA-12154 aparece quando o cliente não encontra esse alias em nenhuma das fontes de resolução configuradas — ou seja, o problema acontece antes de qualquer tentativa de conexão de rede com o banco.

Causas mais comuns

• Alias digitado errado ou inexistente: o nome usado na conexão não bate (nem por um caractere) com a entrada no tnsnames.ora.

• TNS_ADMIN apontando para o diretório errado: se a variável de ambiente TNS_ADMIN estiver definida, o cliente Oracle procura o tnsnames.ora exclusivamente nesse caminho. Se ela apontar para um diretório sem o arquivo (ou com um arquivo desatualizado), o alias correto pode simplesmente não estar visível para aquela sessão.

• Arquivo tnsnames.ora no lugar padrão errado: sem TNS_ADMIN definido, o cliente busca o arquivo em $ORACLE_HOME/network/admin. Ambientes com múltiplos Oracle Homes (comum em servidores com mais de uma versão de client instalada) são fonte frequente desse problema.

• Erro de sintaxe no tnsnames.ora: um parêntese sem par em qualquer entrada do arquivo pode quebrar a leitura de todo o arquivo, não só da entrada com erro.

• String de conexão que não usa alias: quando a aplicação usa o formato Easy Connect (host:porta/service_name) mas o código ou driver está tentando resolver esse valor como se fosse um alias do tnsnames.ora.

  
  

Diagnóstico passo a passo

1. Confirmar onde o cliente está procurando o arquivo:

echo $TNS_ADMIN

Se a variável estiver vazia, o cliente está usando $ORACLE_HOME/network/admin/tnsnames.ora.

1. Verificar se o alias existe no arquivo certo:

cat $TNS_ADMIN/tnsnames.ora

(ou $ORACLE_HOME/network/admin/tnsnames.ora, conforme o passo anterior)

1. Testar a resolução isoladamente, sem tentar autenticar:

tnsping NOME_DO_ALIAS

Se o tnsping já falhar com TNS-03505: Failed to resolve name, o problema é resolução de nome — confirma que não é questão de firewall, listener ou credencial, e sim de configuração do client.

Correção

Na maioria dos casos, a correção é uma destas:

• Corrigir o valor de TNS_ADMIN para apontar para o diretório certo, ou remover a variável se o tnsnames.ora correto já está em $ORACLE_HOME/network/admin.

• Corrigir o nome do alias na string de conexão ou a entrada correspondente no tnsnames.ora.

• Revisar o arquivo em busca de parênteses não fechados — um erro de sintaxe em uma entrada pode invalidar as demais.

• Quando fizer sentido, eliminar a dependência do tnsnames.ora usando Easy Connect diretamente:

sqlplus usuario/senha@host:porta/service_name

Depois de qualquer ajuste, repita o tnsping antes de tentar a conexão completa — é mais rápido isolar o problema de resolução de nome do que testar a stack inteira a cada tentativa.

Fechamento

O ORA-12154 costuma ser rápido de resolver quando alguém já sabe onde olhar — mas em ambientes com múltiplos servidores, múltiplos Oracle Homes e configurações herdadas de anos de operação, cada minuto de troubleshooting é tempo tirado de outra prioridade. É exatamente esse tipo de situação que clientes Siltech não enfrentam: ambientes de banco de dados padronizados, documentados e com monitoramento proativo evitam que um erro simples de configuração de rede vire uma interrupção de produção.