Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

ORA-12514 when connecting to an Oracle database container

ErrorORA-12514: Cannot connect to database. Service ... is not registered with the listener

Short answer

ORA-12514 means the listener got a request for a service name it does not know. With an Oracle container it is usually one of three things: the database is still starting, the service name in your connection string is wrong (for the Free image it is FREEPDB1, not FREE), or you used localhost from another container.

  • Applies to Oracle Database Free 23ai container, Docker Compose 2, gvenzl/oracle-free image
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Ask the listener inside the container which services it knows, and look for READY.

    docker exec -it oracle lsnrctl services
  2. 2Match what you see, then jump to its fix

    1. 1Works a minute later with no changeThe database is still startingFix
    2. 2lsnrctl services does not list the name you usedThe service name in the connection string is wrongFix
    3. 3Works from the host, fails from the app containerAnother container connects to localhostFix

What does the error look like?

  • ORA-12514: Cannot connect to database. Service ... is not registered with the listener
  • Service ... is not registered with the listener at host:port

Cause 1 of 3

The database is still starting

1Check

Oracle lists a just-started database as one that has not finished registering with the listener. The image logs a ready banner when it is done.

docker logs oracle 2>&1 | grep "DATABASE IS READY TO USE"

2Fix

Wait for the banner, or give the container a healthcheck and make dependents wait for it.

services:
  oracle:
    image: gvenzl/oracle-free
    healthcheck:
      test: ["CMD", "healthcheck.sh"]
      interval: 10s
      retries: 30

3Verify

The log shows the banner and lsnrctl lists the service as READY.

docker exec oracle lsnrctl services

Confirmed by github.com

Did this fix it?

Cause 2 of 3

The service name in the connection string is wrong

1Check

Compare the name after the slash in your connection string with what the listener and the database report.

docker exec -it oracle lsnrctl services
# inside sqlplus: SELECT name FROM v$services;

2Fix

Use a name the listener lists. For the Free image the default pluggable database is FREEPDB1, so the connection target is that service, not the instance name FREE.

sqlplus test/test@//localhost:1521/FREEPDB1

3Verify

The login succeeds.

echo 'select 1 from dual;' | sqlplus -s test/test@//localhost:1521/FREEPDB1

Confirmed by docs.oracle.com

Did this fix it?

Cause 3 of 3

Another container connects to localhost

1Check

Inside a Compose network, services reach each other by service name; localhost there is the app container itself.

docker compose exec app printenv DB_HOST

2Fix

Use the service name as host and the container port 1521.

jdbc:oracle:thin:@//oracle:1521/FREEPDB1

3Verify

Restart the app and check its connection log.

docker compose up -d app && docker compose logs --tail 20 app

Confirmed by docs.docker.com

Did this fix it?

How do I stop it coming back?

  • Add a healthcheck and depends_on with condition service_healthy for apps that need the database.
  • Keep host, port and service name in one environment file.
  • Mount a volume at /opt/oracle/oradata so a restart does not rebuild the database.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.