Billionmail/BillionMail · critical

redis connection test failed after 10 attempts

Error message

redis connection test failed after 10 attempts

What it means

InitRedis tries up to 10 times to connect to Redis and run a connectivity test before the application will start. If every attempt fails (e.g. Redis is down, unreachable, or misconfigured), it returns this sentinel error indicating the connection test never succeeded after exhausting all retries. It is thrown because the app depends on Redis at boot and cannot proceed without a verified connection.

Source

Thrown at core/internal/service/redis_initialization/redis_initialization.go:65

		if err := g.Redis().SetEX(context.Background(), k, k, 1); err != nil {
			g.Log().Error(context.Background(), "Redis connection test failed: ", err, " Waiting for 5 seconds before retrying...")
			time.Sleep(5 * time.Second)
			continue
		}

		if _, err := g.Redis().Del(context.Background(), k); err != nil {
			g.Log().Error(context.Background(), "Redis connection test failed: ", err, " Waiting for 5 seconds before retrying...")
			time.Sleep(5 * time.Second)
			continue
		}

		connectionOK = true
		g.Log().Debug(context.Background(), "Redis connection test successful")
		break
	}

	if !connectionOK {
		return fmt.Errorf("redis connection test failed after 10 attempts")
	}

	return nil
}

View on GitHub (pinned to fc36c76c05)

Solutions

1. Verify Redis is running: docker ps / redis-cli -h <host> -p 6379 ping
2. Check Redis connection config (host, port, password) in the app's config file or environment
3. Increase retry window or add depends_on/healthcheck so Redis is ready before the app starts
4. Test connectivity from the app's network context (same Docker network, no firewall block)
5. Inspect app logs for the underlying per-attempt error (auth vs refused vs timeout)

Example fix

// before (docker-compose.yml)
services:
  app:
    depends_on: [redis]
// after
services:
  app:
    depends_on:
      redis:
        condition: service_healthy

func redisReachable(addr string) error {
    conn, err := net.DialTimeout("tcp", addr, 2*time.Second)
    if err != nil { return err }
    return conn.Close()
}
// call before starting the app: if err := redisReachable("127.0.0.1:6379"); err != nil { log.Fatal(err) }

if err := redis_initialization.InitRedis(); err != nil {
    if strings.Contains(err.Error(), "connection test failed") {
        // back off and retry startup, or fall back to degraded mode
        time.Sleep(5 * time.Second)
        return retryInit(3)
    }
    return err
}

When it happens

Trigger: All 10 loop iterations of the connection test fail — Redis service not running, wrong host/port in config, Redis still starting during container orchestration, network/DNS failure, or wrong password (requirepass).

Common situations: Docker Compose where Redis container is not up yet when the app starts; REDIS_HOST pointing at localhost inside a container; Redis restarted/crashed; firewall or Docker network misconfiguration; auth misconfiguration.

Understand the failure class

Background: ECONNREFUSED and "connection refused" / "could not connect to server" errors: what they mean and how to fix them — this error's family across 44 libraries.

Related errors

• failed to connect: %w
• reconnect failed: %w
• redis env init error: %v
• Logout failed: %w
• failed to get validate code: %w

AI-assisted analysis of Billionmail/BillionMail@fc36c76c05 (2026-09-05). Data as JSON: /api/errors/cc2ec107234c2e03. Report an issue: GitHub.