DEV Community

umzzil nng
umzzil nng

Posted on Originally published at oraerror.com

Oracle ORA-12638 Error: Causes and Solutions Complete Guide

#oracle #database #dba #sql

ORA-12638: Credential Retrieval Failed — Causes, Fixes, and Prevention

ORA-12638 occurs when Oracle's Net Services layer fails to retrieve authentication credentials during a client-to-server connection attempt. This error is most commonly triggered by a mismatch between the authentication settings in sqlnet.ora on the client or server side and the actual OS or network authentication environment. It appears frequently in Windows environments using NTS (Native OS Authentication) or in setups involving Oracle Advanced Security.

Top 3 Causes

1. Incorrect SQLNET.AUTHENTICATION_SERVICES Setting in sqlnet.ora

This is the #1 cause of ORA-12638. Setting NTS on Linux/Unix or using an unsupported authentication service for the environment will immediately trigger this error. The fix is straightforward — edit the sqlnet.ora file.

-- Verify current OS authentication settings on the DB server
SELECT name, value
FROM v$parameter
WHERE name IN ('os_authent_prefix', 'remote_os_authent');

-- Check current session authentication type after reconnecting
SELECT sys_context('USERENV', 'AUTHENTICATION_TYPE') AS auth_type,
       sys_context('USERENV', 'OS_USER') AS os_user
FROM dual;
Enter fullscreen mode Exit fullscreen mode

Fix for Linux/Unix (remove NTS):

# sqlnet.ora — Linux/Unix
SQLNET.AUTHENTICATION_SERVICES = (NONE)
Enter fullscreen mode Exit fullscreen mode

Fix for Windows (use NTS or NONE depending on need):

# sqlnet.ora — Windows with domain auth
SQLNET.AUTHENTICATION_SERVICES = (NTS)

# Windows without domain auth
SQLNET.AUTHENTICATION_SERVICES = (NONE)
Enter fullscreen mode Exit fullscreen mode

2. Oracle Wallet Misconfiguration or Missing Wallet

When Oracle Wallet is configured for external authentication or password store, an incorrect wallet path or a closed wallet will cause ORA-12638. Always verify wallet status before troubleshooting further.

-- Check wallet status
SELECT wrl_type, wrl_parameter, status, wallet_type
FROM v$encryption_wallet;

-- Check external password store links
SELECT username, db_link, host
FROM sys.link$
WHERE autologin = 'Y';
Enter fullscreen mode Exit fullscreen mode

Correct sqlnet.ora wallet configuration:

WALLET_LOCATION =
  (SOURCE =
    (METHOD = FILE)
    (METHOD_DATA =
      (DIRECTORY = /oracle/wallet)))
SQLNET.WALLET_OVERRIDE = TRUE
SQLNET.AUTHENTICATION_SERVICES = (NONE)
Enter fullscreen mode Exit fullscreen mode

3. External Authentication User Misconfiguration

If OS-authenticated (external) users are configured incorrectly in Oracle, credential retrieval will fail. The os_authent_prefix parameter must match the external username format exactly.

-- Check externally authenticated users
SELECT username, external_name, authentication_type
FROM dba_users
WHERE authentication_type = 'EXTERNAL'
ORDER BY username;

-- Check OS auth prefix
SELECT name, value
FROM v$parameter
WHERE name = 'os_authent_prefix';

-- Create a properly formatted external user (Windows domain example)
CREATE USER "OPS$DOMAIN\\DBUSER" IDENTIFIED EXTERNALLY;
GRANT CREATE SESSION TO "OPS$DOMAIN\\DBUSER";

-- Verify failed authentication attempts
SELECT username, userhost, timestamp, returncode
FROM dba_audit_session
WHERE returncode = 12638
ORDER BY timestamp DESC;
Enter fullscreen mode Exit fullscreen mode

Quick Fix Checklist

  1. Edit sqlnet.ora — Set SQLNET.AUTHENTICATION_SERVICES=(NONE) on Linux/Unix or confirm (NTS) is valid on Windows.
  2. Restart the listener — Changes to sqlnet.ora require a listener restart: lsnrctl stop && lsnrctl start.
  3. Check wallet status — Run SELECT status FROM v$encryption_wallet; and open if closed.
  4. Enable SQL*Net tracing for deeper diagnosis: 
# Add to sqlnet.ora temporarily for debugging
TRACE_LEVEL_CLIENT = SUPPORT
TRACE_FILE_CLIENT = sqlnet_client_trace
DIAG_ADR_ENABLED = OFF
Enter fullscreen mode Exit fullscreen mode

Prevention Tips

1. Standardize and version-control sqlnet.ora
Maintain a single approved sqlnet.ora template across all environments (dev, test, prod) and store it in a version control system like Git. Any change must go through a review and validation process before deployment.

2. Monitor authentication failures proactively
Enable session auditing to catch ORA-12638 occurrences early:

-- Enable audit for failed logins
AUDIT CREATE SESSION WHENEVER NOT SUCCESSFUL;

-- Review failed login audit trail
SELECT username, userhost, terminal,
       timestamp, returncode
FROM dba_audit_session
WHERE returncode = 12638
ORDER BY timestamp DESC
FETCH FIRST 10 ROWS ONLY;
Enter fullscreen mode Exit fullscreen mode

Set up alerts in Oracle Enterprise Manager or a custom monitoring script to notify the DBA team immediately when this error appears in alert logs.

Related Errors

  • ORA-12641 — Authentication service failed to initialize (same root cause)
  • ORA-12637 — Packet receive failed (network layer drop during auth)
  • ORA-01017 — Invalid username/password (often accompanies auth failures)
  • ORA-12650 — No common encryption algorithm (Advanced Security mismatch)

📖 Want a more detailed guide?
Check out the full in-depth version (Korean) on oraerror.com — includes detailed analysis, additional SQL examples, and prevention tips.

Top comments (0)