Resolve database connection errors during Jira server startup
Platform Notice: Server and Data Center Only - This article only applies to Atlassian products on the server and data center platforms.
During Installation, Upgrade or Startup, JIRA performs a number of checks. The Database Connection check verifies that JIRA can connect to a Database, as this is vital for JIRA to run.
The reasons for this check to fail are:
- You don't have a database running
- The configuration in your
- Username/Password for your database are 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
The JIRA instance needs a database in order to run. Without a database, it can't read any previously created Issues or store newly created issues.
Given that there's a number of reasons this could be happening, there are a few things you may need to check to resolve this.
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
Fix: Check 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 accessible. Follow the information for your specific database to achieve this.
Check ports needed for the database connection
If that is successful check if the PORT your database tries to connect to is available
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 seconds
Fix: 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, or
- 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> 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
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 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 probably want to check which port is actually opened 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.