Route Planner Configuration

The Route Planner allows Lavalink to rotate through multiple IP addresses to avoid rate limiting and IP bans from audio sources. This is particularly useful when handling high-traffic loads or when certain sources implement aggressive rate limiting.

Overview

Route Planner uses IP blocks (CIDR blocks) to rotate outgoing connections across different IP addresses. When configured properly, it helps:

Avoid Rate Limits

Distribute requests across multiple IPs to stay under rate limits

Handle Bans

Automatically switch IPs when one gets banned

Improve Reliability

Continue operating even when some IPs are blocked

Scale Traffic

Support higher request volumes across multiple addresses

Terminology

IP Block / CIDR Block

An IP block is a collection of IP addresses, usually contiguous and described in CIDR notation.Examples:

192.168.1.0/24 - 256 IPv4 addresses (192.168.1.0 to 192.168.1.255)
2001:db8::/64 - 2^64 IPv6 addresses
10.0.0.0/8 - 16,777,216 IPv4 addresses

For more information about CIDR blocks, refer to Understanding CIDR Notation.

Combined IP Block

When multiple CIDR blocks are configured in the ipBlocks array, Lavaplayer treats them as a single virtual IP block.Example:

ipBlocks:
  - "1.0.0.0/24"
  - "2.0.0.0/24"
  - "2001:db8::/64"

These are combined into one pool for rotation strategies.

Configuration

Configure the Route Planner in your application.yml:

application.yml

lavalink:
  server:
    ratelimit:
      ipBlocks:
        - "1.0.0.0/8"
        - "2001:db8::/64"
      excludedIps:
        - "1.0.0.1"
      strategy: "RotateOnBan"
      searchTriggersFail: true
      retryLimit: -1

Configuration Parameters

lavalink.server.ratelimit.ipBlocks

array

required

List of IP blocks in CIDR notation to use for rotation.Example:

ipBlocks:
  - "1.0.0.0/8"      # IPv4 block
  - "2001:db8::/64"  # IPv6 block

lavalink.server.ratelimit.excludedIps

array

Specific IP addresses to exclude from the rotation pool.Example:

excludedIps:
  - "1.0.0.1"           # Exclude specific IPv4
  - "2001:db8::1"       # Exclude specific IPv6

lavalink.server.ratelimit.strategy

string

required

IP rotation strategy to use.Options:

RotateOnBan - Switch IP when banned
LoadBalance - Random IP selection
NanoSwitch - Nanosecond-based switching
RotatingNanoSwitch - Rotating nanosecond-based switching

See Strategies for detailed information.

lavalink.server.ratelimit.searchTriggersFail

boolean

default:"true"

Whether a search 429 (Too Many Requests) response should trigger marking the IP as failing.

true - Search rate limits trigger IP rotation
false - Only playback rate limits trigger rotation

lavalink.server.ratelimit.retryLimit

integer

default:"-1"

Number of retry attempts for failed requests.

-1 - Use default Lavaplayer value
0 - Infinite retries
>0 - Specific number of retry attempts

Environment Variables

LAVALINK_SERVER_RATELIMIT_IP_BLOCKS=["1.0.0.0/8","2001:db8::/64"]
LAVALINK_SERVER_RATELIMIT_EXCLUDE_IPS=["1.0.0.1"]
LAVALINK_SERVER_RATELIMIT_STRATEGY=RotateOnBan
LAVALINK_SERVER_RATELIMIT_SEARCH_TRIGGERS_FAIL=true
LAVALINK_SERVER_RATELIMIT_RETRY_LIMIT=-1

Strategies

RotateOnBan Strategy

Uses the RotatingIpRoutePlanner which switches to a new IP address as soon as the current one gets banned.

Overview
Configuration
Use Cases

How it works:

Uses one IP address at a time
When a ban is detected, immediately rotates to the next IP
Cycles through all available IPs in the block

Best for:

IPv4 blocks
IPv6 blocks with bitmask < /64
Smaller IP pools
Predictable rotation patterns

application.yml

lavalink:
  server:
    ratelimit:
      ipBlocks:
        - "192.168.1.0/24"  # 256 addresses
      strategy: "RotateOnBan"

LoadBalance Strategy

Uses the BalancingIpRoutePlanner which randomly selects IP addresses from the configured blocks.

Overview
Configuration
Use Cases

How it works:

Randomly selects an IP for each request
Distributes load across all available IPs
No specific rotation order

Best for:

Large IP blocks
High traffic loads
Services with strict per-IP rate limits

Some services ban IPs after just a few automated requests per day. You should have a large IP block to effectively use this strategy.

application.yml

lavalink:
  server:
    ratelimit:
      ipBlocks:
        - "10.0.0.0/16"     # 65,536 addresses
        - "2001:db8::/48"   # Large IPv6 block
      strategy: "LoadBalance"

NanoSwitch Strategy

Uses the NanoIpRoutePlanner which switches IPs based on the current nanosecond clock offset.

Overview
Configuration
Use Cases

How it works:

Uses current nanosecond timestamp as offset in IP block
Changes IP on each clock update
Provides extremely rapid IP rotation

Requirements:

At least a /64 IPv6 block (2^64 addresses)
IPv6-capable network infrastructure

If your CIDR block is larger than /64, consider using RotatingNanoSwitch instead for better ban handling.

application.yml

lavalink:
  server:
    ratelimit:
      ipBlocks:
        - "2001:db8::/64"  # Exactly /64 required
      strategy: "NanoSwitch"

RotatingNanoSwitch Strategy

Uses the RotatingNanoIpRoutePlanner which combines nanosecond switching with /64 block rotation on bans.

Overview
Configuration
Use Cases

How it works:

Uses nanosecond offset within the current /64 block
When a ban occurs, rotates to the next /64 block
Provides both rapid rotation and ban resilience

Requirements:

At least one /64 IPv6 block (2^64 addresses)
For effective rotation: at least two /64 blocks

Not recommended to combine different-sized blocks (e.g., two /65s). Use multiple /64 blocks or larger for best results.

application.yml

lavalink:
  server:
    ratelimit:
      ipBlocks:
        - "2001:db8:1::/64"
        - "2001:db8:2::/64"
        - "2001:db8:3::/64"
      strategy: "RotatingNanoSwitch"

Or a larger block:

lavalink:
  server:
    ratelimit:
      ipBlocks:
        - "2001:db8::/48"  # Contains 65,536 /64 blocks
      strategy: "RotatingNanoSwitch"

Strategy Comparison

Strategy	Min IPs Required	Rotation Method	Ban Handling	Best For
RotateOnBan	Any size block	Sequential on ban	Switch to next IP	IPv4, small blocks
LoadBalance	Large blocks	Random selection	Avoid banned IPs	High traffic, large pools
NanoSwitch	/64 IPv6	Nanosecond offset	None (single /64)	Extreme rotation
RotatingNanoSwitch	Multiple /64s	Nano + block rotation	Switch /64 block	Best IPv6 strategy

IPv6 Setup

Before using IPv6-based strategies, you need to configure IPv6 on your server. See the IPv6 Setup Guide for detailed instructions for various hosting providers.

Hetzner

Just 3 commands to setup

Contabo

Built-in /64 address

DigitalOcean

16 IPv6 addresses or Tunnelbroker

Complete Examples

IPv4 RotateOnBan
IPv6 NanoSwitch
IPv6 RotatingNanoSwitch
Mixed IPv4/IPv6

application.yml

lavalink:
  server:
    ratelimit:
      ipBlocks:
        - "192.168.1.0/24"  # 256 addresses
      excludedIps:
        - "192.168.1.1"     # Gateway
        - "192.168.1.255"   # Broadcast
      strategy: "RotateOnBan"
      searchTriggersFail: true
      retryLimit: 3

application.yml

lavalink:
  server:
    ratelimit:
      ipBlocks:
        - "2001:db8::/64"
      strategy: "NanoSwitch"
      searchTriggersFail: true
      retryLimit: -1

application.yml

lavalink:
  server:
    ratelimit:
      ipBlocks:
        - "2001:db8::/48"  # Large block with many /64s
      strategy: "RotatingNanoSwitch"
      searchTriggersFail: true
      retryLimit: 5

application.yml

lavalink:
  server:
    ratelimit:
      ipBlocks:
        - "10.0.0.0/16"     # IPv4 block
        - "2001:db8::/64"   # IPv6 block
      excludedIps:
        - "10.0.0.1"
      strategy: "LoadBalance"
      searchTriggersFail: true
      retryLimit: -1

Testing Your Configuration

After configuring the Route Planner, verify it’s working correctly:

Check Logs

Look for Route Planner initialization messages in the Lavalink logs:

INFO - Route planner initialized with strategy: RotateOnBan
INFO - IP blocks: [1.0.0.0/8]

Monitor IP Usage

Use the REST API to check which IPs are being used:

curl http://localhost:2333/v4/routeplanner/status \
  -H "Authorization: youshallnotpass"

Test Rotation

Make multiple requests and verify different IPs are being used (check external service logs or use IP tracking).

Test Ban Handling

Simulate a ban and verify the strategy rotates to a new IP appropriately.

Troubleshooting

IPs Not Rotating

Check:

Route Planner is configured correctly in application.yml
IP blocks are in valid CIDR notation
Strategy is specified and valid
Lavalink has permission to bind to the IP addresses
IPv6 is properly configured on your server (if using IPv6)

All IPs Getting Banned

Possible causes:

IP block is too small for your traffic volume
Requests are too frequent for the strategy
Source service has very aggressive rate limiting

Solutions:

Get a larger IP block
Switch to LoadBalance or NanoSwitch strategy
Reduce request frequency
Implement request queuing

Cannot Bind to IPv6 Addresses

Verify IPv6 is configured: ping6 google.com
Check nonlocal bind is enabled: sysctl net.ipv6.ip_nonlocal_bind
Verify route is configured: ip -6 route show
See IPv6 Setup Guide for detailed instructions

Strategy Not Working as Expected

Verify you meet the minimum requirements for the strategy
Check that IP blocks are the correct size
Review logs for strategy initialization messages
Ensure excluded IPs aren’t blocking rotation
Try a different strategy to compare behavior

Best Practices

Choosing a Strategy

Small IP pools (less than 256 addresses): Use RotateOnBan
Large IPv4 pools: Use LoadBalance
Single IPv6 /64: Use NanoSwitch
Multiple IPv6 /64s or larger: Use RotatingNanoSwitch

IP Block Sizing

Monitor your traffic and ban rates
Start with a conservative block size
Expand if you’re hitting rate limits
For IPv6: /64 minimum, /48 recommended for production

Monitoring

Set up alerts for high ban rates
Monitor IP rotation frequency
Track which IPs are banned most often
Log rate limit responses for analysis

Production Deployment

Test thoroughly in a staging environment
Start with conservative settings
Monitor closely after deployment
Have a rollback plan ready
Document your configuration

IPv6 Setup

Configure IPv6 on your server

application.yml Reference

Complete configuration reference

Get Started

Configuration

Clients & Plugins

Route Planner Configuration

Overview

Avoid Rate Limits

Handle Bans

Improve Reliability

Scale Traffic

Terminology

Configuration

Configuration Parameters

Environment Variables

Strategies

RotateOnBan Strategy

LoadBalance Strategy

NanoSwitch Strategy

RotatingNanoSwitch Strategy

Strategy Comparison

IPv6 Setup

Hetzner

Contabo

DigitalOcean

Complete Examples

Testing Your Configuration

Troubleshooting

Best Practices

IPv6 Setup

application.yml Reference

Build docs developers (and LLMs) love

Get Started

Configuration

Clients & Plugins

​Overview

Avoid Rate Limits

Handle Bans

Improve Reliability

Scale Traffic

​Terminology

​Configuration

​Configuration Parameters

​Environment Variables

​Strategies

​RotateOnBan Strategy

​LoadBalance Strategy

​NanoSwitch Strategy

​RotatingNanoSwitch Strategy

​Strategy Comparison

​IPv6 Setup

Hetzner

Contabo

DigitalOcean

​Complete Examples

​Testing Your Configuration

​Troubleshooting

​Best Practices

​Related Resources

IPv6 Setup

application.yml Reference

Build docs developers (and LLMs) love

Overview

Terminology

Configuration

Configuration Parameters

Environment Variables

Strategies

RotateOnBan Strategy

LoadBalance Strategy

NanoSwitch Strategy

RotatingNanoSwitch Strategy

Strategy Comparison

IPv6 Setup

Complete Examples

Testing Your Configuration

Troubleshooting

Best Practices

Related Resources