Resolve database connection errors during Jira DC startup
Platform Notice: Data Center Only - This article only applies to Atlassian apps on the Data Center platform.
Note that this KB was created for the Data Center version of the product. Data Center KBs for non-Data-Center-specific features may also work for Server versions of the product, however they have not been tested. Support for Server* products ended on February 15th 2024. If you are running a Server product, you can visit the Atlassian Server end of support announcement to review your migration options.
*Except Fisheye and Crucible
Summary
During Installation, Upgrade, or Startup, Jira performs several checks. The Database Connection check verifies that Jira can connect to a Database, which is vital for Jira to run.
Cause
The reasons for this check to fail are:
You don't have a database running.
The configuration in your
dbconfig.xmlis incorrect.Username/Password for your database is incorrect.
Your database user doesn't have the correct permissions to connect to the database.
The database specified is not the Jira database.
You're trying to use an incorrect port.
General network issues that prevent Jira from connecting to your database include:
Postgres/MySQL localhost errors.
Firewall errors.
Network connection not available/offline.
On upgrading Jira to 10.3.5 and later versions, the following error may be observed in the atlassian-jira.log:
Could not successfully test your database:
java.sql.SQLRecoverableException: Listener refused the connection with the following error:
ORA-12514, TNS:listener does not currently know of service requested in connect descriptorImpact
The Jira instance needs a database to run. Without a database, it can't read previously created Issues or store newly created issues.
Solution
Given that there are a number of reasons this could be happening, there are a few things you may need to check to resolve it.
ℹ️ These steps don't apply when using the embedded H2 database. If you have issues with the embedded H2 database, you can refer to the following article to verify access to it: Access the H2 embedded database.
Network issue
Check to see if your network is up and check if your database is reachable for your Jira instance.
Ping your database server
Can you ping your Database server? Take the URL for your database that's in your dbconfig.xml and ping your database:
ping 123.456.789.012
Fix: Check that your database is running
If you can't ping the database, it may not be running. Make sure your database server is running on the specified address and is accessible. Follow the information for your specific database to achieve this.
Check the ports needed for the database connection
If that is successful, check if the PORT your database tries to connect to is available.
nmap 123.456.789.012
Is the port you need open?
It should probably look something like this (in this example for Postgres):
❯ nmap 123.456.789.012
Starting Nmap 7.40 ( https://nmap.org ) at 1970-01-01 0:00 AEDT
Nmap scan report for 123.456.789.012
Host is up (0.00083s latency).
Not shown: 498 closed ports, 498 filtered ports
PORT STATE SERVICE
5432/tcp open postgresql
Nmap done: 1 IP address (1 host up) scanned in 13.27 secondsFix: Check your database and database settings for external connections
If this is not the case, two things may be happening:
The host you point to might be running - ping was successful - but there is no database running.
Your database only allows connections from localhost. This is the default setting for several database servers, such as Postgres or MySQL. Check the information for your specific database on how to setup your database to allow external connections.
Does your user have the correct permissions?
In order to read from and write to the database, the user specified in your dbconfig.xml file needs to have the right permissions.
Check your database to see if the user in your dbconfig.xml has the correct permissions.
In Postgres, you can run this:
(you need to replace <user>, <database>, <host>, <port>, and <user> with the appropriate values for this query to work)
psql -U <user> -d <database> -h <host> -p <port> -c "select * from information_schema.role_table_grants where grantee='<user>';"If you see quite a lot of lines of output, everything should be fine.
If you see a fatal error, this may be a hint that the permissions are wrong.
Some example errors in Postgres (values in <value> would be your input):
- missing user: psql: FATAL: role "<user>" does not exist
- missing database: psql: FATAL: database "<database>" does not exist
Fix: Set up a correct user and/or database
The fix here is different for each database type. Follow the instructions for your specific database on how to setup your database user with the correct permissions.
Check the correct PORT
Every database runs on a certain default port (Postgres has a default port of 5432, for example).
Make sure the port specified in your dbconfig.xml is correct.
Try to connect to your database via the command line. If you see an error like this in Postgres:
psql: could not connect to server: Connection refused
Is the server running on host "<host>" and accepting
TCP/IP connections on port <port>?Fix: Check the ports
If that is the case, you should probably check which port is actually open for your database, if at all. (See networking checks above.)
To find out if the database is exposed on a certain port at all, try the nmap check as described above as well.
Jira to 10.3.5 and later versions
If the solution mentioned in the Jira fails to connect to Oracle 19c after upgrade to version 10.3.5+, the KB article does not help, please check the contents of the <jira-install>/atlassian-jira/WEB-INF/lib directory to ensure that an older version of the JDBC driver is not present.
If present, remove or move the driver JAR file to a different path, but don't leave it in your WEB-INF/lib directory, even if you rename it.
Was this helpful?