Home / OCI

OCITroubleshootingIntermediate

Can't connect to Autonomous Database: wallet, mTLS, ACL and ORA- errors

Fix the usual Autonomous Database connection failures by checking mTLS vs TLS, the wallet location, access control lists, private endpoints and service names.

Deepak Bhardwaj3 min read

Applies toOracle Autonomous Database Serverless (ATP/ADW), SQL*Plus, SQLcl, JDBC thin

Know your connection mode

Mode Requires Port
mTLS (default) Client wallet (cwallet.sso, tnsnames.ora, sqlnet.ora) 1522
TLS (walletless) Require mTLS turned off, and an ACL or private endpoint configured 1521 or 1522 
oci db autonomous-database get --autonomous-database-id $ADB \
  --query 'data.{mtls:"is-mtls-connection-required", acl:"whitelisted-ips", pe:"private-endpoint", state:"lifecycle-state"}'

Download and use the wallet (mTLS)

oci db autonomous-database generate-wallet --autonomous-database-id $ADB \
  --password 'WalletPassw0rd!' --file wallet_prod.zip
mkdir -p ~/wallets/prod && unzip -o wallet_prod.zip -d ~/wallets/prod
export TNS_ADMIN=~/wallets/prod
sqlplus admin@proddb_high

Make sure sqlnet.ora points at the real directory:

WALLET_LOCATION = (SOURCE = (METHOD = file) (METHOD_DATA = (DIRECTORY="?/network/admin")))

Replace ?/network/admin with the full wallet path, or rely on TNS_ADMIN. JDBC thin needs ?TNS_ADMIN=/path/to/wallet in the URL.

Error map

Error Cause Fix
ORA-12506: TNS:listener rejected connection based on service ACL filtering Client IP or VCN not in the access control list Add the client's public IP/CIDR or VCN to the ACL
ORA-28759: failure to open file Wallet directory wrong or unreadable Fix WALLET_LOCATION / TNS_ADMIN and file permissions
ORA-29024: Certificate validation failure Old wallet after a certificate rotation, or a proxy intercepting TLS Download a fresh wallet. Bypass TLS inspection for the ADB host.
ORA-12170 / ORA-12541 / timeout Network: firewall blocks 1522, or private endpoint not reachable Allow egress to 1522. For a private endpoint, check the NSG, routes and DNS.
ORA-01017: invalid username/password Wrong credentials, or the user is locked Reset as ADMIN: ALTER USER app IDENTIFIED BY "..." ACCOUNT UNLOCK;
ORA-12514 / service not found Wrong service alias, or the DB was renamed/cloned Use the tnsnames.ora entries from the current wallet
Connections refused while the DB is STOPPED Auto-stop schedule, or stopped manually Start the DB, and review its schedule

Private endpoint checks

  • The client is in, or routed to, the VCN, and the NSG on the private endpoint allows 1522 (and 1521 for TLS) from the client.
  • The private endpoint host name resolves from the client: nslookup <hostname>.adb.<region>.oraclecloudapps.com. On-premises DNS needs forwarding to the VCN resolver.

Choose the right service

_tp / _tpurgent for OLTP, _low / _medium / _high for reports and analytics. A high service runs fewer concurrent statements, so an app that opens many sessions on _high will queue. Use _tp or _low for applications.

Tip

Wallets don't expire often, but they do change when certificates rotate. Store the wallet in OCI Vault or your secret manager, and script downloading a fresh one.

Related fixes