Metasploit "Database Not Connected" on Kali: msfdb, PostgreSQL and the Fix

If db_status says "postgresql selected, no connection", run sudo msfdb init (or sudo msfdb start if you already initialized it once), then relaunch msfconsole. Database not connected almost never means anything is broken. It means Kali did exactly what it was built to do: it never starts your own local database on boot, on purpose, along with every other network service on the system.

Why Kali does this to you, on purpose

Every other Linux distribution you've probably used starts its background services and leaves them running. Kali is built differently on purpose: it's a penetration testing platform, and a service quietly listening on a port is exactly the kind of thing that gives away your position on an engagement or opens a door nobody meant to open. So Kali's Network Services Policy disables persistence for network-facing services by default, and that includes PostgreSQL, the database Metasploit uses to store hosts, credentials, loot, and scan results.

That's the part almost nobody explains when they answer this error. It isn't that PostgreSQL crashed, or that your install is corrupted, or that you did something wrong during setup. It's that Kali rebooted, and rebooting shut PostgreSQL back off, and nothing turned it on again. db_status is reporting exactly what it sees: no connection, because there's genuinely nothing listening on port 5432 yet.

The fix, in full, step by step

This is the sequence Kali's own documentation gives, and it's genuinely all most readers need. Run it from a terminal:

1. Start and initialize the database in one command: sudo msfdb init. On a machine that's never set this up before, you'll see PostgreSQL start, a database user called "msf" get created, two databases ("msf" and "msf_test") get created, a configuration file get written, and the schema get built.
2. Launch Metasploit: msfconsole -q (the -q just skips the banner art, so you get straight to the prompt).
3. Confirm it took: at the msf6 > prompt, type db_status. A working connection reports something like "Connected to msf. Connection type: postgresql." — not "no connection."
4. If you'd rather skip a step, sudo msfdb run does the start-and-init in one shot and then drops you straight into msfconsole automatically.

If you already ran msfdb init on a previous session — the databases and config file already exist, you just need PostgreSQL running again — skip straight to sudo msfdb start, then launch msfconsole. Running init again is harmless and won't wipe existing data, but it's an unnecessary extra step when start does the same job faster.

Why old guides show different msfdb output than yours

If you've compared your terminal against a video or a forum post and the prompts didn't match — different questions asked, different flags, an interactive password prompt you never saw — you haven't done anything wrong. Kali maintains its own version of msfdb, distinct from the one that ships with a standard, non-Kali Metasploit install. Kali's own documentation flags this directly rather than pretending the two are identical.

Which message are you actually seeing?

"Database not connected" is a category, not one specific problem. The exact wording tells you which fix you actually need — and running the wrong fix (usually msfdb reinit, which deletes and rebuilds everything) is how people lose scan data over an error that only needed a service restart.

Root vs. your everyday account: two different config files

Here's a source of real confusion that has nothing to do with your install being broken and everything to do with which account ran which command. Metasploit's database config, database.yml, can live in one of two places, and Metasploit only reads one of them at a time:

• System-wide: /usr/share/metasploit-framework/config/database.yml — written when you run sudo msfdb init, and shared by everyone on the machine who runs Metasploit as root or with root privileges via msfdb.
• Per-user: ~/.msf4/database.yml — written when a plain, non-root msfconsole session prompts you to set up a database on first run, or when you manually copy a config there.

The practical upshot: be consistent about which account you use for Metasploit. If you always run sudo msfdb init and always launch with plain msfconsole (no sudo), you can end up with a system-wide config that root can see and a session that's looking in your home directory instead, finding nothing, and reporting "no connection" or a missing config even though a database genuinely exists on the machine.

When both config files exist and disagree

This is the messier cousin of the problem above. If you've ever run Metasploit both as root and as your normal user on the same machine, you can end up with a database.yml in both locations — one pointing at one database, the other pointing at a different one (or at nothing, if it's stale). Metasploit will pick whichever one applies to the account you're currently running as, and it won't warn you that a second, conflicting file exists.

The clean fix is to pick one account and stick with it. If you've decided your everyday non-root user is the one you want, move the root-created file out of the way rather than deleting it outright, in case you need to compare the two:

sudo mv /usr/share/metasploit-framework/config/database.yml /usr/share/metasploit-framework/config/database.yml.bak

Then run msfdb init as your normal user (no sudo) so a fresh, consistent ~/.msf4/database.yml gets created for the account you'll actually be launching msfconsole from.

"Password authentication failed for user msf"

This one is genuinely different from "no connection" and deserves to be treated that way. PostgreSQL is up, Metasploit can reach it, and the "msf" database role exists — but the password stored in database.yml doesn't match what PostgreSQL has for that role anymore. This usually happens after a msfdb reinit that created a new password, while an older database.yml copy (say, one you'd backed up, or one Armitage or another tool is still pointing at) still has the previous one.

The most reliable fix is not to hand-edit the password in two places and hope they match — it's to let msfdb regenerate both sides together:

Run sudo msfdb reinit, answer "no" when asked whether to delete existing database content, and let it rewrite the config and the role's password together so both sides agree again.

"Permission denied" on your own database.yml

If Metasploit reports it can't open ~/.msf4/database.yml, or can't write to ~/.msf4/logs/, the file or folder is almost always owned by a different user than the one running msfconsole right now. This happens the same way every time: you ran something with sudo once (maybe just once, out of habit), it created files as root inside your home folder's .msf4 directory, and now your normal, non-root account can't read or write them.

Check ownership first, don't guess:

ls -la ~/.msf4

If the files are listed as owned by root instead of your own username, hand them back:

sudo chown -R $USER:$USER ~/.msf4

Then relaunch msfconsole as your normal user. If the ~/.msf4 folder doesn't exist at all — which can happen if you try msfdb init before ever running plain msfconsole once — create it first with mkdir -p ~/.msf4, then run msfdb init again.

"Database not connected or cache not built" — a different problem wearing the same words

This message shows up when you run a command like search inside msfconsole, not at startup, and it's easy to mistake for the same connection problem. It isn't, necessarily. Check db_status first — if that reports a real connection, your database is fine, and this message is only telling you the module search cache hasn't been built yet.

Run db_rebuild_cache at the msf6 > prompt to fix it. On a full, unmodified framework this can take a few minutes the first time, since it's indexing every loaded module against the database, not just the ones you've used. It doesn't need to be run every session — the cache persists once built. The times it's worth running again: after installing new modules or plugins, or after an update visibly adds new modules to the framework and search isn't finding them.

Why it worked yesterday and stopped working today

This is the single most common version of this question, and it isn't really a bug report — it's the Network Services Policy doing its job. Every clean reboot returns PostgreSQL to "off," on every Kali install, on every host. If your database connected fine last week and doesn't now, and you haven't changed any config, the very first thing to try — before touching passwords, permissions, or configs — is simply sudo msfdb start.

When nothing above fixes it: starting clean

If you've worked through the symptom table above and you're still stuck — mismatched configs, permission errors that won't clear, or a database.yml that seems to reference a database that no longer exists — a clean rebuild is the honest last resort. It's disruptive, so treat it as the final step, not the first one.

1. Back up anything you care about first. If you have workspaces with real engagement data, export them (db_export) before deleting anything.
2. Wipe the database and its config: sudo msfdb delete. This removes the web-service and database configuration files; you'll be asked separately whether to also delete the database's contents.
3. Rebuild from nothing: sudo msfdb init, as the one account you've decided to standardize on (see the root-vs-user section above).
4. Verify with a fresh console: close any open msfconsole sessions entirely and start a new one, then run db_status again. An old session won't pick up a rebuilt database on its own.

Making PostgreSQL start automatically — and the trade-off nobody mentions

If typing one command before every session genuinely bothers you, you can override Kali's default and enable PostgreSQL at boot with sudo systemctl enable postgresql. It will then survive reboots on its own, and db_status should show a connection the moment msfconsole opens, without a msfdb start first.

Custom ports and pointing Metasploit at a config by hand

If you're running PostgreSQL on a non-default port — for instance, to avoid a clash with another instance already on 5432 — msfdb init accepts the port as an argument: msfdb init 5433. Not sure which port your current config actually uses? Check before you troubleshoot further: cat ~/.msf4/database.yml (or the system-wide path if you're running as root) shows the host, port, username, and database name it's set to connect with.

If Metasploit is still reading the old port after that, or you want to point it at a specific config file directly, use db_connect from inside msfconsole: db_connect -y /path/to/database.yml loads that file's settings and connects immediately, which is also the fastest way to confirm whether a specific config file is even valid before you spend time troubleshooting anything else.

Multiple users, remote sessions, and headless boxes

Two situations that don't come up in the basic walkthrough but do come up in the real world:

More than one person using the same Kali install. Because the per-user database config lives at ~/.msf4/database.yml, each separate non-root account on the machine gets its own database automatically, with no extra setup and no risk of two people's workspaces colliding — home directories don't overlap. If two accounts both need root-level access instead, though, they'll share the single system-wide config, and whoever ran msfdb reinit most recently resets it for everyone using it that way.

Running over SSH. Nothing about msfdb or msfconsole cares whether you're at the physical keyboard or connected remotely — the commands in this post work identically either way, because you're still running them locally on that machine. What's out of scope here is reaching a Metasploit database running on a different machine over the network; that involves opening PostgreSQL's own listening configuration and access rules beyond the local, single-host setup msfdb creates by default, and is a broader topic than this post covers.

Other tools reading the same database

msfconsole isn't the only thing that talks to this database. Armitage, the Java-based GUI front end for Metasploit that Kali also packages, connects to the same database.yml Metasploit uses, via an environment variable pointing at its path. If Armitage reports it can't connect while a plain msfconsole session in the same terminal profile shows a working connection, the usual cause is the same duplicate-config problem covered earlier — Armitage is reading a different, stale copy of the file than the one your console session is using.

Whether it's worth bothering with Armitage at all depends on what you want. If you're comfortable at the command line, msfconsole plus workspaces covers the same ground with far fewer moving parts to keep in sync, and it's the tool this post — and most current documentation — is written around. Armitage is worth reaching for specifically when you want a visual, collaborative view of a team engagement, not as a requirement for getting a database working.

Frequently asked questions

Why does msfconsole say "no connection" every time I open a new terminal?

Because PostgreSQL only stays running until you close that terminal session or reboot — Kali doesn't keep it running across sessions by default. Run sudo msfdb start at the beginning of each working session, or set up autostart if you understand and accept the trade-off in the autostart section above.

Is msfdb start the same as msfdb init?

No. init creates the database, the "msf" user, and the config file — do it once. start just switches PostgreSQL back on when everything already exists. Running init repeatedly is harmless but unnecessary; use start for everyday use.

Do I need PostgreSQL for Metasploit to work at all?

No — Metasploit runs fine without a database connected. You lose specific conveniences: saved hosts and credentials across sessions, faster module search, workspace-based organization of scans, and commands like db_nmap that log results directly to the database. For anything beyond a single quick exploit, it's worth having.

Why does db_status say connected but search still says "Database not connected or cache not built"?

That message covers two unrelated situations in one sentence. If db_status confirms a real connection, the issue is only that the search cache hasn't been indexed yet — run db_rebuild_cache. It only needs re-running after new modules or plugins are added, not every session.

What does msfdb reinit actually delete?

It rebuilds the database user, the databases, and the config file, and it separately prompts you about whether to delete existing database content. Answer "no" to that specific prompt if you only want credentials and config regenerated — say "no" and your workspaces, hosts, and loot stay intact.

I ran msfdb init as root once, and now my regular user gets "Permission denied" — why?

Because sudo created files under ~/.msf4 owned by root, and your non-root account can't read or write them anymore. Run sudo chown -R $USER:$USER ~/.msf4 to hand the folder back to your own account.

Why does my database.yml keep pointing to msf_test instead of msf?

msf_test is a separate database Metasploit creates alongside msf for its own test suite — it isn't meant to hold your working data. If your active config is somehow pointing at it, that's a sign the config was hand-edited or copied incorrectly; rerun msfdb init to regenerate a correct one rather than editing the port or database name by hand.

Can I make PostgreSQL start automatically at boot so I don't have to do this every time?

Yes, with sudo systemctl enable postgresql, but it works against Kali's Network Services Policy — you're leaving a service listening across reboots on purpose. Fine on a machine that never leaves a trusted network; worth reconsidering on one that does.

What's the difference between /usr/share/metasploit-framework/config/database.yml and ~/.msf4/database.yml?

The first is the system-wide config, written by sudo msfdb init and used when you run Metasploit with root privileges. The second is per-user, written the first time a non-root msfconsole session sets up a database, and used by that specific account. Metasploit only reads whichever one matches how you're currently running it.

I get "FATAL: password authentication failed for user msf" — what changed?

PostgreSQL and your config disagree about the "msf" account's password, usually because msfdb reinit generated a new one somewhere along the line while an older copy of database.yml is still in use. Run sudo msfdb reinit again, saying no to deleting your data, so both sides get regenerated together.

I searched and found "MDB2 Error: connect failed" — is that my problem?

Almost certainly not this one. That specific error string comes from an unrelated PHP database library (PEAR's MDB2), not from Metasploit's PostgreSQL adapter — current Metasploit uses Ruby's ActiveRecord and the pg gem, and doesn't produce that message. If you've seen it referenced alongside this problem, it's worth double-checking the actual message your own terminal shows rather than assuming it applies.

Does db_nmap require the database too?

Yes — db_nmap is specifically the database-backed version of an Nmap scan; it runs Nmap and writes the results straight into your active workspace. Without a database connection it will either fail or fall back to a plain scan with no results saved, depending on your Metasploit version.

I'm running Metasploit inside Docker or WSL — does msfdb init still work the same way?

The commands are the same, but the failure mode can look different. A container or WSL distribution that isn't running a full init system can throw errors like "System has not been booted with systemd as init system (PID 1). Can't operate." followed by "Failed to connect to bus: Host is down" when msfdb tries to manage PostgreSQL through systemctl. If you see that specific pair of messages, the issue is the init system inside your container or WSL distribution, not your Metasploit setup — check that environment's own documentation for starting background services without full systemd.

How do I check if PostgreSQL itself is actually running, separate from Metasploit?

sudo msfdb status reports the systemd service state directly. You can also check ss -ant and look for port 5432 in the listening state — if it's not there, PostgreSQL isn't running, regardless of what Metasploit reports.

Will msfdb delete remove my loot and workspaces permanently?

It can — you're prompted separately about deleting the database's contents when you run it, and if you say yes, that data is gone unless you exported it first with db_export. If you only want the config and web-service credentials reset, decline that specific prompt.

I changed the PostgreSQL port — how do I tell Metasploit about it?

Run msfdb init with the new port as an argument, for example msfdb init 5433, so the generated config matches. If a database already exists on the new port and you just need Metasploit to find it, use db_connect -y /path/to/database.yml pointing at a config file with the correct port set.

Revision note. Written August 2026, covering current Kali Linux releases and Metasploit's default PostgreSQL-backed database setup via msfdb. This will need a fresh look if a future Kali release changes the default database backend or the msfdb command set. If you've been going in circles on this one for a while, take a breath — it really is usually just one missing command, not a broken install.Happy Breaking folks!