Jira Cannot Connect to Its Database at Startup Check the Database Before Touching Jira

Jira without its database is a library with no books. When startup stops at the database stage, the fault is usually in the database's world - not in Jira's. Check there first.

✍️ Technical Anshu🪟 Windows Server⏱️ 9 minute read

🎥 Watch the full fix in the video — every step shown live on screen

Every project, issue, user and permission in Jira lives in its database, so Jira checks that connection early and refuses to continue without it. The confusing part is that 'Jira cannot connect to the database' has at least five different causes: the database service is down, the credentials in Jira's config are wrong, the database drive is full, the database is busy recovering, or a stale lock file survived a crash. This page separates them calmly, in the order you should test them.

Jira startup screen in the browser (illustration)

Jira had problems starting up

Database: Jira is unable to connect to the database. The connection may have failed due to an incorrect JDBC URL, unavailable database server, or invalid credentials. Check the logs for the underlying error and correct the configuration in dbconfig.xml.

The startup check page Jira shows when the database stage fails. Example wording shown as an illustration.

First Question - Is the Database Itself Alive

After a shared reboot, databases often start slower than Jira expects, and after a hard crash they can sit in recovery for a long time while appearing 'running'. A Jira that failed at 9:00 sometimes starts perfectly at 9:10 with no fix at all - because the database finished recovering.

Open services.msc on the database server and confirm the database service (SQL Server, PostgreSQL, MySQL or Oracle) is Running
Open the database's own management tool and try to log in and open the Jira database
If the database shows a state like Restoring or Recovery pending, wait for it to finish - restarting Jira impatiently will not speed it up
Check the database server's own error log for the same time window; a database that rejected the connection usually says why

Check dbconfig.xml Against Reality

Jira reads its database address and credentials from one file: dbconfig.xml, in the Jira home directory. If the database moved, its port changed, or the Jira database user's password was changed inside the database only, this file is now lying to Jira - and Jira believes the file.

Open dbconfig.xml in the Jira home directory - on a standard Windows install the home directory sits under C:\Program Files\Atlassian\Application Data\Jira
Compare the server name or IP, port, database name and username with the database's real values
Test the exact same username and password with the database's own tool, from the Jira server itself - a login that works locally but not across the network points at firewall or network, not credentials
If the password changed, update it in the database or in this file so both sides agree - and write down that you did, for the next admin
Never delete dbconfig.xml to 'reset' Jira: you would be deleting the map to every project you own

The Full Disk and the Locked Database

Two causes hide behind the same symptom. A database drive at 100 percent makes the database refuse or drop connections with errors that look like corruption. And after a crash, Jira can fail with a locked message: Jira protects its home directory with a lock file, and a lock left behind by a dead process convinces the new process that Jira is 'already running'.

Check free space on every drive the database uses, including the drive holding its transaction logs
Free space by moving old backups off the drive - not by shrinking or deleting live database files
For the lock: stop the Jira service and confirm in Task Manager that no Jira java.exe process remains
Only then, look for .jira-home.lock in the Jira home directory and delete that one file
Start the service - with the stale lock gone, Jira creates a fresh lock and proceeds
If a real Jira process is still running, do not delete the lock: it is doing its job, and removing it can corrupt data

What the Logs Say at This Stage

The atlassian-jira.log in the log folder of the Jira home directory records the database handshake in detail. Search it for the connection error: a 'login failed' message means credentials; a 'connection refused' or timeout means the server or network; a JDBC driver error means the address or database name in dbconfig.xml is wrong. Let the exact wording choose your fix instead of trying all five.

Open the newest atlassian-jira.log and find the startup attempt by time
Search for ERROR lines mentioning database, JDBC or connection
Read the Caused by line - it carries the database's own error, in the database's own words

🔴 The golden rule of this stage: prove the database healthy with the database's own tools before changing anything in Jira. Most 'Jira database errors' are fixed in the database - a started service, a finished recovery, a freed disk, a corrected password. And whatever you change, back up dbconfig.xml first; it is a small file that holds the keys to the whole system.

🎥 See the Complete Fix in the Video

The full Jira startup repair, step by step, with the exact screens and log lines shown live.

▶️ Watch Full Video

❓ Common Questions (FAQ)

Where does Jira store its database connection settings

In dbconfig.xml, inside the Jira home directory. It holds the JDBC URL (server, port and database name), the username, and the password. If the database server moves or the Jira database password changes, this file must be updated to match, or every startup will fail at the database stage.

Jira says the database is locked. Is my data damaged

Usually not. In most cases it is the stale .jira-home.lock file: Jira creates it while running, and a crash or forced shutdown can leave it behind, so the next start believes another Jira is already using the home directory. Stop the service, confirm no Jira Java process is running, delete that single lock file, and start again. Only delete it when you are certain Jira is fully stopped.

The database password was changed. How do I tell Jira the new one

Edit the password inside dbconfig.xml in the Jira home directory so it matches the password set in the database, then restart the Jira service. Test the same credentials with the database's own tool first - if the database itself rejects them, fix the account in the database rather than guessing in the file.

This guide is based on the Technical Anshu video on fixing a Jira that will not start • Stuck on a step? Ask in the video comments — you will get a reply 🙏