You launch msfconsole, wait for it to load, and the banner ends with the line that ruins the session: database support disabled. Or it loads clean but db_status reports postgresql selected, no connection. Now db_nmap does nothing useful, hosts is always empty, and every module run has to be re-entered by hand because nothing is being remembered.
The Metasploit database is not part of Metasploit. It is a PostgreSQL server that Metasploit connects to, and almost every “database not connected” report is a PostgreSQL problem wearing a Metasploit costume. Fix the server and the console follows.
Confirm what is actually broken
Run these two commands and read them carefully — they separate the failure modes:
msf6 > db_status
msf6 > exit
$ cat ~/.msf4/database.yml
| What you see | What it means |
|---|---|
postgresql selected, no connection | Config exists, server is not reachable — cause 1–3 |
database support disabled and no database.yml | The database was never initialised — cause 4 |
Connected to msf. Connection type: postgresql. | The database is fine; your problem is elsewhere |
database.yml exists but db_status shows a connection error with a password line | Credentials do not match — cause 3 |
1. PostgreSQL is not running
The single most common cause. Kali and most Debian-based installs ship PostgreSQL but do not necessarily have it enabled as a service, and a reboot or a VM snapshot restore leaves it stopped.
sudo systemctl start postgresql
sudo systemctl enable postgresql # survive reboots
systemctl status postgresql --no-pager
Then reconnect from the console:
msf6 > db_disconnect
msf6 > db_connect
msf6 > db_status
If systemctl reports the service failed to start, read its log before anything else: journalctl -u postgresql -n 50 --no-pager. The usual offenders are a full disk, a stale postmaster.pid after an unclean shutdown, or a port already taken.
2. The socket path is wrong after an upgrade
PostgreSQL listens on a Unix socket in /var/run/postgresql/ by default. Distribution upgrades that change the PostgreSQL major version also change the socket directory contents, and a database.yml written by an older install points at a socket that no longer exists.
Check what the server is actually offering:
ls /var/run/postgresql/
sudo -u postgres psql -c "SHOW port;"
Then compare with your connection config in ~/.msf4/database.yml. If the paths disagree, the clean repair is to regenerate the config rather than hand-edit it:
msfdb reinit
reinit wipes the Metasploit database — hosts, loot, notes, credentials from previous engagements — and builds a fresh one. If you have data in there worth keeping, export it first from a working console with db_export -f xml backup.xml, or fix the config by hand instead.
3. The credentials in database.yml do not match
Metasploit authenticates to PostgreSQL as a dedicated role, usually msf. If the role’s password was changed, or the file was written by another install of Metasploit, authentication fails and the console reports no connection.
Verify from the shell that the role and password work at all:
sudo -u postgres psql -c "\du"
You should see an msf role in the list. If it is missing, or if logging in with the password from database.yml fails, rebuild instead of fighting it:
msfdb delete
msfdb init
That combination removes the role and the database and creates both again, writing a matching database.yml. It is the documented repair path and it is faster than reconciling passwords by hand.
4. The database was never initialised
A fresh install, or a Metasploit installed without the Kali metapackage, has no database at all. The console then starts with database support disabled because there is nothing to connect to.
msfdb init
msfconsole
msf6 > db_status
On Kali there is also a msfdb reinit shortcut in the same script family, and msfdb status will tell you whether the service and the database both exist before you open the console at all.
5. You are running as the wrong user
The database.yml file lives in the home directory of whoever ran msfdb init. Run sudo msfconsole and you are root, looking at /root/.msf4/; run it as your normal user and you are looking somewhere else entirely. One of the two has a config, the other does not, and switching between them makes the database appear and disappear at random.
Pick one identity and stay there. Running the console as root is its own problem — it makes every file a module writes root-owned, and the standard advice is to run as a normal user and use sudo only for the parts of a test that need raw sockets.
6. A previous instance still holds the connection
PostgreSQL limits concurrent connections, and a crashed console can leave sessions open until they time out. If you have restarted msfconsole many times in one session, especially after hangs, the server may be refusing new connections.
sudo -u postgres psql -c "SELECT count(*) FROM pg_stat_activity;"
If the count is at the limit, restart the service to clear the stale backends: sudo systemctl restart postgresql. Long-lived labs should also raise the limit in postgresql.conf rather than restarting in a loop.
Working without the database
Everything that matters for running an engagement still works without a database connection — the database is a notebook, not an engine. What you lose:
db_nmap— use plainnmapand import afterwards withdb_import scan.xmlonce the database is back.- Automatic recording of hosts, services and credentials — keep notes by hand or export after each module run.
hosts,services,credsandlootqueries — the commands return empty results, which is not an error.- Workspace separation between engagements — everything lands in the default workspace once the connection returns.
If a deadline is looming, continue without the database and repair it afterwards. db_import accepts nmap XML and Metasploit output, so nothing is lost permanently.
Verify the repair
| Command | Expected result |
|---|---|
systemctl status postgresql | active (running) |
msf6 > db_status | Connected to msf |
msf6 > workspace | Lists default |
msf6 > db_nmap -sV 127.0.0.1 | Scan runs and hosts afterwards shows the target |
msf6 > hosts | Non-empty after an import or scan |
The last two are the real test: a connection that reports success but records nothing is a half-fixed install.
Checklist
- Run
db_statusand read the exact message before changing anything. sudo systemctl start postgresql— solves the majority of cases.- No
database.yml? Runmsfdb init. - Config exists but will not authenticate? Run
msfdb deletethenmsfdb init. - After an OS upgrade,
msfdb reinitto rewrite paths and sockets. - Stay as one user; do not alternate between root and your account.
- Prove it with
db_nmapandhosts, not justdb_status.
Frequently asked questions
What does “database support disabled” mean in msfconsole?
It means Metasploit found no database configuration to connect to — usually ~/.msf4/database.yml is missing because msfdb init has never been run. The fix is one command: msfdb init, then restart the console.
Do I need the database to use Metasploit?
No. Modules, payloads, sessions and the handler all work without it. The database adds persistence and querying — recorded hosts, services, credentials and loot across a session — which matters for large engagements and report writing but not for running a single module.
Where does Metasploit store its database connection settings?
In ~/.msf4/database.yml for the user running the console. It contains the adapter, database name, username, password and host. If two terminal sessions see different database behaviour, they are running as different users with different copies of that file.
msfdb init fails with a permission error. What now?
The script needs to create a PostgreSQL role, which requires database superuser rights. On Kali, run sudo msfdb init once. If PostgreSQL itself refuses to start, fix that first with journalctl -u postgresql — msfdb cannot initialise against a dead server.
See also: Meterpreter Session Died / "Is Not Valid" — when the session opens and then vanishes.