How to Fix Plugin Database Connection Failed Errors

Direct answer

Read the full database error before editing credentials. “Connection refused”, “Access denied”, “Unknown host” and “Communications link failure” point to different causes.

What it means

SQL-backed plugins may fail when a server is unreachable, its port is blocked, a database account lacks host permissions, TLS settings disagree, or the connection pool is exhausted. SQLite file locking is a different issue and should not be treated as MySQL networking.

If you are a player

1. Report which plugin feature is unavailable. Do not ask an administrator to share a database password or screenshot connection strings in public chat.

If you run the server

1. Stop or isolate the failing plugin on a backup/test instance and record the earliest SQL exception in logs/latest.log. Redact passwords and connection URLs before sharing diagnostics.
2. If the error is “Unknown host” inspect the configured hostname and DNS; for “Connection refused” confirm that the database is running and listening on the intended TCP port, with firewall/access policies allowing the server host.
3. For “Access denied”, check the database user, password, allowed client host and database grants. Avoid granting administrative privileges to an ordinary Minecraft plugin.
4. For pool exhaustion or timeout, inspect the database connection count and plugin pool configuration against the plugin’s own documentation. Do not automatically increase every timeout or maximum.

References

• MySQL: Access denied
• MySQL: Lost connection
• PaperMC adding plugins

Related fixes and guides