Tuesday, October 23, 2012

Troubleshooting SQL: Developer Connection Problems

This article is intended to help with troubleshooting SQL Developer connection problems. It won't tell you how to set up a connection because that is already well covered online help (Start with the Getting Started topic and follow the link from there.)

The article is limited to the SQL Developer BASIC connection type. That is a simple JDBC type 4 connection with no additional authentication or security options, and no additional oracle client software.

What is a connection?

When you connect to an oracle instance using SQL Developer, you are making a TCP/IP connection to a specific host, on a specific port, and to a named instance or service. These are the parameters you supply when creating a basic connection in SQLDeveloper.
  • host

    This can be a hostname or an IP address. If you use a hostname, including localhost, your workstation must be able to resolve it to an IP address.

  • port

    This is the TCP port on the host which is listening for oracle connections. It is usually 1521, but not always.

  • SID

    This the instance name of the database

  • service

    This is the service name under which the database is available. It is often the same as the SID, but may not be.

These details should be available from your DBA, or from when you created a database.

In the remainder of this article there is an assumption that you have the correct details. There is always the possibility that you have the wrong information or have mistyped something. If a test fails, re-check your information before investigating other causes.

The database host and your workstation may be the same machine — you may have SQL Developer installed on the database host, or you may have an oracle database installed on your PC — but you still need a TCP/IP connection. In this article I will use the terms host and workstation to distinguish the two.

Connection Errors

This is not a comprehensive list of oracle errors, or even all errors relevant to SQL Developer connections.

See the Oracle Error messages reference manaual for all error messages.

  1. Client Side Errors

    These are errors caused by issues on the workstation, or somewhere between the workstation and the host. If you get either of these errors, follow the troubleshooting tips at Basic Network Connectivity Below

    • Status : Failure -Test failed: IO Error: The Network Adapter could not establish the connection
    • An error was encountered performing the requested operation: IO Error: The Network Adapter could not establish the connection Vendor code 17002
  2. Host side errors

    These are errors caused by issues on the host such as the database service not running. In each case you will need to contact the team responsible for the host.

    • Status : Failure -Test failed: Listener refused the connection with the following error: ORA-12514, TNS:listener does not currently know of service requested in connect descriptor.

      This means that the service you have specified is not running.

    • Status : Failure -Test failed: Listener refused the connection with the following error: ORA-12505, TNS:listener does not currently know of SID given in connect descriptor

      This means that the SID you have specified is not running.

    • Status : Failure -Test failed: IO Error: Got minus one from a read call

      This is a non-specific error, but I have seen it when the remote database is shutting down.

    • Status : Failure -Test failed: Listener refused the connection with the following error: ORA-12528, TNS:listener: all appropriate instances are blocking new connections

      This can mean that either the database is still starting up, or that the database is overloaded (too many connections.)

    • Status : Failure -Test failed: ORA-01034: ORACLE not available ORA-27101: shared memory realm does not exist Linux Error: 2: No such file or directory

      This means that the database is down.

    • Status : Failure -Test failed: ORA-01033: ORACLE initialization or shutdown in progress

      This means that the database is in the process of starting or stopping.

  3. Other errors

    These are not SQL Developer specific connection errors, but may mean you can't connect.

    • Status : Failure -Test failed: ORA-01017: invalid username/password; logon denied

      This is self-explanatory. Either your username or password is wrong.

    • An error was encountered performing the requested operation: ORA-28000: the account is locked 28000. 00000 - "the account is locked" *Cause: The user has entered wrong password consequently for maximum number of times specified by the user's profile parameter FAILED_LOGIN_ATTEMPTS, or the DBA has locked the account *Action: Wait for PASSWORD_LOCK_TIME or contact DBA Vendor code 28000

      The account you are using is locked. You will need to contact your security administrator or DBA.

Basic Network Connectivity

These tests use a windows command window and windows tools. Tools on other platforms may produce different responses.
  1. Can you ping the host?
    Q:\tests>ping mercure
    Ping request could not find host mercure. Please check the name and try again.
    This indicates that the host "mercure" isn't known to your workstation. Typically this means that there is no DNS entry, or no HOSTS file entry.
    Q:\tests>ping hermes
    Pinging hermes.ponder-stibbons.local [] with 32 bytes of data:
    Request timed out.
    Request timed out.
    Request timed out.
    Request timed out.
    Ping statistics for
        Packets: Sent = 4, Received = 0, Lost = 4 (100% loss),
    This indicates that the host "hermes" is known to your workstation, but the host itself is not accessible. The host could be down, or there could be a DNS error (i.e. wrong IP address,) or your network configuration means that your workstation cannot reach it.
    Q:\tests>ping mercury
    Pinging mercury.ponder-stibbons.local [] with 32 bytes of data:
    Reply from bytes=32 time<1ms TTL=64
    Reply from bytes=32 time=5ms TTL=64
    Reply from bytes=32 time<1ms TTL=64
    Reply from bytes=32 time<1ms TTL=64
    Ping statistics for
        Packets: Sent = 4, Received = 4, Lost = 0 (0% loss),
    Approximate round trip times in milli-seconds:
        Minimum = 0ms, Maximum = 5ms, Average = 1ms
    This is a successful test, you can now proceed to the next stage.
  2. Can you telnet to the host on the correct port?
    Q:\tests>telnet mercury 1522
    Connecting To mercury...Could not open connection to the host, on port 1522: Connect failed
    This could mean that the listener is not running, or that a firewall is blocking the port. The firewall could be on the database host, on your workstation or anywhere in between.
    Q:\tests>telnet mercury 1521
    If you get a blank screen here, you have successfully connected. Type ctrl-] to get the telnet command line and quit.
    Welcome to Microsoft Telnet Client
    Escape Character is 'CTRL+]'
    Microsoft Telnet> quit
    If something other than an oracle listener is using port 1521 you may still get a blank screen, or you may see a welcome message. This is unlikely if you have the correct host.
  3. Can other oracle clients connect?
    $ tnsping xe
    TNS Ping Utility for 64-bit Windows: Version - Production on 19-OCT-2012 10:47:47
    Copyright (c) 1997, 2011, Oracle.  All rights reserved.
    Used parameter files:
    Used TNSNAMES adapter to resolve the alias
    Attempting to contact (DESCRIPTION = (ADDRESS = (PROTOCOL = TCP)(HOST = mercury.ponder-stibbons.local)(PORT = 1521))
    OK (20 msec)


  • Other connection types connections (TNS,LDAP, Advanced, Local/Bequeath)
  • Oracle client software interactions
  • diagnostic tools

Update History

Date Amendment
19 Oct 2012 Initial version

Sunday, June 17, 2007

Advanced Security Option Gotcha

Here is nice little licensing anomaly. Advanced Security Option (ASO) implements, among other things the 'identified globally' clause of 'create user'. It is an Enterprise Edition option, and an EE option generally means big bucks.

However it looks as if using 'identified externally' with Windows domain accounts counts as 'identified globally'.

select name,
from   dba_feature_usage_statistics 
where  name like 'Advanced Security';

------------------ ----- --------------------
Advanced Security  FALSE 19-MAY-2007 01:03:06

create user MYDOMAIN\JIM identifed externally;

You now have to wait for the feature audit job to run to pick up the new feature. The job appears to run weekly. If you know how to force a feature audit, please let me know.

Once the job has run, if you rerun the query, you can see that the Advanced Security Option is enabled, and you could be in breach of your license.
select name,
from   dba_feature_usage_statistics 
where  name like 'Advanced Security';

NAME               CURRE LAST_USAGE_DATE     
------------------ ----- --------------------
Advanced Security  TRUE  26-MAY-2007 23:44:07 

My current client has only a few databases on windows, and does not generally use external authentication, but each windows server has a couple of service accounts for backups and other operations and these are normally externally authenticated domain accounts.


Wednesday, February 21, 2007

Symantec releases Veritas Storage Foundation as freeware

Symantec have release a version of Veritas Storage Foundation as freeware. It seems to be aimed at small businesses running small servers as it is limited to creating 4 volumes / file systems and will only run on 2 processor machines.

It is available for Solaris 8,9,10 (SPARC), Solaris 10 (x64), AIX 5.2,5.3, RHEL4 (XEON/EM64T/Opteron/Itanium 2), SLES 9,10 (XEON/EM64T/Opteron/Itanium 2) and Windows 2000 and 2003.

This is good news for small companies as the licence cost of Storage Foundation used to be a significant overhead. If you are buying commodity hardware and putting a free operating system on it, then the $1000 or so SF used to cost is significant.

It is also good news for me as it means that my home lab set up can now include even more software I am likely to use at client sites.

More on this when I have tried it out.

Tuesday, February 06, 2007

OTN Single sign-on is forever

I've recently given up an old email address which I no longer used, except as my contact point for OTN. This meant that I also had to give up my OTN account because the security software for OTN does not let you change your email address. It doesn't matter that much, but it means I have lost all my brownie points and my little gold medal for being an active user.

It is very annoying however. The forum software they use allows email addresses to be changed out of the box but they have modified it to disable this. I thought at first it was part of the move to a single sign-on approach to bring it in to line with metalink where your email address is your userid. But no, metalink allows you to change your email address even though it your userid.

And don't get me started on the fact that you can't change your password either.

The "Editor-in-Chief" of OTN says it is out of his hands.

Fear of 11i

I'm not looking forward to 11i.

I'm sure there will be all sorts of exciting new features designed to make me redundant, but the main reason is that I'll have to upgrade my lab machines.

Each new version has increased the minumum hardware requirements, but it is usually possible to run Oracle below the minimum requirements if all you are doing is single user experimentation. There are exceptions though. I tried to run Grid Control on a machine with 512MB of RAM (the recommended minimum is 1024MB) and I spent more time dealing with OC4J crashes than tring out grid control.

Most of my lab machines are so old that they are not worth upgrading - either they are at the maximum RAM or the RAM is no longer readily available.

When I finally bite the bullet, I will probably invest in something big and state of the art which can support at least 2 VMWare virtual machines concurrently.

Monday, December 04, 2006

Using CVS with SQLDeveloper

This entry describes a very simple implementation of CVS as an external tool in Oracle's SQLDeveloper database ide. Integrated version control is promised for later releases, but until then an external tools implementation is the best that can be done.

The external tools interface is new in version 1.1 which is currently going through a preview cycle. There are limitations in the external tools interface which make it difficult to work with CVS in the way I would like to.

The external script

This is a windows batch file.
All it does is change directory to the source file directory and issue a commit.

@echo off
pushd %1
cvs commit -m%3 %2

The external tool definition

  1. Goto Tools > External Tools

    If this is the first time you have used the dialog, you will be prompted to set up some automatic definitions.
  2. Click on New and fill in the fields as follows

    • Program Executable:  <full path of batch file>
    • Arguments: ${file.dir} ${file.name} "${promptl:label=Checkin comment} "

      The quotes round the final parameter are necessary because if can contain spaces. If your pathnames or file names contain spaces, the other parameters will need to be quoted too.
    • Run Directory: <directory containing batch file>

  3. Click Next

    As of build 2197 there are a couple of error dialogs to click through at this stage. They don't seem to affect the functionality.
  4. Fill in the display options as follows

    • Caption for Menu Items: C&VS commit

      This will set V as the accelerator for menu options.
    • ToolTip Text: Commit the current file to CVS
    • Icon Location: (Leave as default)

  5. Click Next
  6. Fill in the Integration options as appropriate. I haven't experimented with these, but you should have at least the tools menu selected. You should probably also check the Reload Open Files box.
  7. Fill in the display options as follows

    • Add items to Menus: 

      • Tools Menu - checked
      • Navigator Context menu - unchecked
      • Code Editor Context Menu - checked1

    • Add Buttons to Toolbars: 
        Main toolbar - Unchecked

    • After Tool Exits: 
      • Reload Open Files - Checked.

        This should ensure that if the file is modified during the commit (by keyword expansion for example), the new version is loaded into SQLDeveloper. NB. As of version, this causes the buffer to be closed

  8. Click Next
  9. File in the Availability options as follows.
    • Enabled: When specific file types are selected.
    • Selected types: 

      • SQL Script
      • Text Document
      • PlSqlNode1

  10. Click Finish

Note 1. These options will make the menu option available when editing PL/SQL in the database as well as in source files.


  • Only works on one file at a time
  • Only works on FILES, not other object nodes.
  • No access to the database. In the case of PL/SQL files I would like to be able to resubmit them to the database after checkin (so that the checkin comments and version numbers are up to date in the database. The external tools interface doesn't reliably provide connection details to allow this.


  • You can replace the commit command with other cvs commands, or you can make the cvs command a prompted parameter.
  • You can replace cvs with another version control tool.

Thursday, November 23, 2006

What is my database called? (Part 1)

Naming oracle databases - Part 1
There are many names which can be considered the database name, depending on the point of view.
  • DBID - system generated database identifier
  • SID - System IDentifier
  • DB_NAME - The real name of the database.
  • GLOBAL_NAME - combination of DNAME and DBDOMAIN
  • DB_UNIQUE_NAME - used in data guard to distinguish between copies of the same database
  • SERVICE - the 'published' name under which end users would access a databas


This is not strictly a name, but is the one absolutely constant identfier for a database. It is generated when you create a database and if you are lucky you will never see it again. It becomes important if you have to restore a database on to a clean machine. You can find the DBID by querying V$DATABASE.


This is the system - or instance - identifier. The instance is the set of processes which manage the database. The SID is used as the environment variable ORACLE_SID and is key to database admin tasks such as starting and stopping the database. You specify the SID when you create the instance.


This IS the name of the database, but for most purposes is largely irrelevant. You never connect to a database, you connect to an instance or a service. You specify the db_name when you create the database by setting the DB_NAME initialisation parameter. The DB_NAME can be different from the instance name, but (except in the case of a RAC setup) there is no real reason to make it different.


This is where it starts to get complicated. The service is the public face of the database and is what clients connect to. The complexity arises because the service name can be defined in 3 different places - in the database; in the listener; and in the client.

In the database

Since Oracle8i, a running instance publishes its availability by registering with a listener. The SERVICE_NAMES initialisation parameter defines the name(s) to be registered. The default is the same as SID.

In the listener

You can override the self-registered name by added service entries to the listener configuration LISTENER.ORA.
This entry creates a "service" called BLOG, which uses the ODBUAD1 instance. The output from "lsnrctl status" shows this service and the self-registered service "ODDBUAD1"

C:\var\logs>LSNRCTL status

LSNRCTL for 32-bit Windows: Version - Production on 23-NOV-2006 11:58:47

Listening Endpoints Summary...
Services Summary...
Service "BLOG" has 1 instance(s).
Instance "ODBUAD1", status UNKNOWN, has 1 handler(s) for this service...
Service "ODBUAD1" has 1 instance(s).
Instance "ODBUAD1", status READY, has 1 handler(s) for this service...
The command completed successfully

In the client

The services a client can connect to are defined in TNSNAMES.ORA. A typical tnsnames entry looks like this

(ADDRESS = (PROTOCOL = TCP)(HOST = dbserver)(PORT = 1521))

This entry defines a "service" called BLAG, which connects to the service defined on the server as BLOG (which in turn uses the database ODBUAD1).

While it is possible to have several different names in several different places for the same database, and multiple names sometimes have their uses, for ease of management it is generally best to keep all the names the same. In a non-RAC environment the main use for different names is to isolate users from changes in the backend.