Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Databases and Redis

NestJS connects to MySQL at ::1 and is refused

ErrorError: connect ECONNREFUSED ::1:3306

Short answer

::1 is the IPv6 loopback address. Your app resolved localhost to it, but MySQL is listening only on IPv4 127.0.0.1, so the connection is refused. Set the host to 127.0.0.1, or make Node prefer IPv4 addresses. You can also change MySQL's bind_address so it listens on IPv6 too.

  • Applies to NestJS 11, TypeORM 0.3, Node.js 22, MySQL 8.4
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Ask the OS which addresses MySQL is listening on. If you see 127.0.0.1:3306 but no [::1]:3306, the cause is the address family.

    sudo ss -ltnp | grep 3306
  2. 2Match what you see, then jump to its fix

    1. 1ECONNREFUSED ::1:3306 while a mysql client with -h 127.0.0.1 worksThe client resolves localhost to ::1 while MySQL listens on IPv4 onlyFix
    2. 2A specific bind_address is set, and only that address accepts connectionsMySQL is bound to an address that excludes the one the client usesFix

What does the error look like?

  • Error: connect ECONNREFUSED ::1:3306

Cause 1 of 2

The client resolves localhost to ::1 while MySQL listens on IPv4 only

1Check

Node's dns.lookup returns addresses in the order the operating system gives them (the default order is verbatim), so localhost can come back as ::1 first.

node -e "require('dns').lookup('localhost',{all:true},(e,a)=>console.log(a))"
mysql -h 127.0.0.1 -P 3306 -u root -p -e "select 1"

2Fix

Use the IPv4 address as the host in the TypeORM options. Alternatively tell Node to put IPv4 first for the whole process.

TypeOrmModule.forRoot({
  type: 'mysql',
  host: '127.0.0.1',
  port: 3306,
  // ...
})

// main.ts, before NestFactory.create
import dns from 'node:dns';
dns.setDefaultResultOrder('ipv4first');

3Verify

Start the app; the connection is made and the error is gone.

npm run start:dev

Confirmed by nodejs.org

Did this fix it?

Cause 2 of 2

MySQL is bound to an address that excludes the one the client uses

1Check

MySQL accepts connections only on the exact address when bind_address is a regular IPv4 or IPv6 address.

mysql -u root -p -e "SHOW VARIABLES LIKE 'bind_address'"

2Fix

Set bind_address to * (all IPv4 and IPv6 interfaces if the host supports IPv6) or :: in the MySQL option file, then restart the server. Only open it beyond loopback if you also restrict access with a firewall.

# my.cnf, [mysqld] section
bind_address = *

3Verify

The listening sockets now include an IPv6 one.

sudo ss -ltnp | grep 3306

Confirmed by dev.mysql.com

Did this fix it?

How do I stop it coming back?

  • Write 127.0.0.1 instead of localhost in database settings.
  • Take the host from an environment variable so containers and laptops can differ.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.