Fix Error: connect ECONNREFUSED 127.0.0.1:6379 - Redis connection to localhost:6379 failed in NestJS

This error occurs when the NestJS Bull/BullMQ queue module cannot connect to Redis because the Redis server is not running or is unreachable at the configured host and port. Fix it by starting Redis, verifying the connection config, and adding connection retry logic in the queue module registration.

Reading the Stack Trace

Here's what each line means:

• at TCPConnectWrap.afterConnect [as oncomplete] (node:net:1494:16): The TCP connection to Redis was refused because nothing is listening on port 6379.
• at BullModule.registerQueue (node_modules/@nestjs/bull/dist/bull.module.js:48:22): The NestJS Bull module tried to establish a Redis connection during queue registration at startup.
• at bootstrap (src/main.ts:12:3): The application fails to bootstrap because the queue module cannot initialize without Redis.

Common Causes

// app.module.ts
BullModule.forRoot({
  redis: {
    host: 'localhost',
    port: 6379,
  },
})
// Redis is not running

BullModule.forRoot({
  redis: {
    host: 'localhost', // Should be redis.internal.svc
    port: 6379,
  },
})

BullModule.forRoot({
  redis: { host: 'localhost', port: 6379 },
  // No retry strategy configured
})

The Fix

Use environment variables for Redis connection details so each environment can configure its own Redis instance. Add a retryStrategy with exponential backoff so the app retries transient connection failures instead of crashing immediately.

import { BullModule } from '@nestjs/bull';
import { Module } from '@nestjs/common';

@Module({
  imports: [
    BullModule.forRoot({
      redis: {
        host: 'localhost',
        port: 6379,
      },
    }),
    BullModule.registerQueue({ name: 'email' }),
  ],
})
export class AppModule {}

import { BullModule } from '@nestjs/bull';
import { Module } from '@nestjs/common';

@Module({
  imports: [
    BullModule.forRoot({
      redis: {
        host: process.env.REDIS_HOST || 'localhost',
        port: parseInt(process.env.REDIS_PORT, 10) || 6379,
        password: process.env.REDIS_PASSWORD || undefined,
        maxRetriesPerRequest: 3,
        retryStrategy: (times: number) => {
          if (times > 10) return null; // Stop retrying after 10 attempts
          return Math.min(times * 200, 5000);
        },
      },
    }),
    BullModule.registerQueue({ name: 'email' }),
  ],
})
export class AppModule {}

Testing the Fix

import { Test, TestingModule } from '@nestjs/testing';
import { getQueueToken } from '@nestjs/bull';
import { EmailProcessor } from './email.processor';

describe('EmailProcessor', () => {
  let processor: EmailProcessor;

  const mockQueue = {
    add: jest.fn().mockResolvedValue({ id: '1' }),
    process: jest.fn(),
  };

  beforeEach(async () => {
    const module: TestingModule = await Test.createTestingModule({
      providers: [
        EmailProcessor,
        { provide: getQueueToken('email'), useValue: mockQueue },
      ],
    }).compile();

    processor = module.get<EmailProcessor>(EmailProcessor);
  });

  it('should be defined', () => {
    expect(processor).toBeDefined();
  });

  it('adds a job to the queue', async () => {
    await mockQueue.add('sendWelcome', { to: 'user@example.com' });
    expect(mockQueue.add).toHaveBeenCalledWith('sendWelcome', { to: 'user@example.com' });
  });
});

Run your tests:

npm test

Pushing Through CI/CD

git checkout -b fix/nestjs-queue-redis-connection,git add src/app.module.ts src/processors/__tests__/email.processor.spec.ts,git commit -m "fix: add Redis retry strategy and env-based config for Bull queues",git push origin fix/nestjs-queue-redis-connection

Your CI config should look something like this:

name: CI
on:
  pull_request:
    branches: [main]
jobs:
  test:
    runs-on: ubuntu-latest
    services:
      redis:
        image: redis:7
        ports:
          - 6379:6379
        options: >-
          --health-cmd "redis-cli ping"
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
      - run: npm ci
      - run: npm test -- --coverage
        env:
          REDIS_HOST: localhost
          REDIS_PORT: 6379
      - run: npm run build

The Full Manual Process: 18 Steps

Here's every step you just went through to fix this one bug:

1. Notice the error alert or see it in your monitoring tool
2. Open the error dashboard and read the stack trace
3. Identify the file and line number from the stack trace
4. Open your IDE and navigate to the file
5. Read the surrounding code to understand context
6. Reproduce the error locally
7. Identify the root cause
8. Write the fix
9. Run the test suite locally
10. Fix any failing tests
11. Write new tests covering the edge case
12. Run the full test suite again
13. Create a new git branch
14. Commit and push your changes
15. Open a pull request
16. Wait for code review
17. Merge and deploy to production
18. Monitor production to confirm the error is resolved

Total time: 30-60 minutes. For one bug.

npm install bugstack-sdk

import { initBugStack } from 'bugstack-sdk'

initBugStack({ apiKey: process.env.BUGSTACK_API_KEY })

Deploying the Fix (Manual Path)

1. Ensure Redis is running and accessible from the application environment.
2. Configure REDIS_HOST and REDIS_PORT environment variables.
3. Add retry strategy to handle transient connection failures.
4. Run tests with a Redis service to verify queue operations.
5. Open a PR, merge after CI, and verify queue processing in staging.

Frequently Asked Questions