Migrate Sidekiq from Heroku Redis to Redis Cloud Pro without CROSSSLOT errors

Redis Cloud Pro databases can introduce sharded Redis behavior, while many Heroku Redis deployments used with Sidekiq behave like a single-node Redis endpoint. This difference can impact how Sidekiq interacts with Redis, especially when multiple keys are accessed in a single operation. During migration, this may result in errors such as CROSSSLOT Keys in request don't hash to the same slot, which can prevent workers from processing jobs.

This article explains how to identify CROSSSLOT risk before migration, how to choose the safest migration approach for Sidekiq, how to perform a controlled cutover, and how to troubleshoot worker issues after switching to Redis Cloud Pro.

Quick Fix

Prerequisites

• Access to your Heroku application and current Redis connection settings

• Access to the Redis Cloud Console and ability to create a Redis Cloud Pro database

• Ability to update environment variables and restart application components

• Access to Sidekiq logs during testing and migration

• A staging environment or a defined maintenance window

• A rollback plan to restore the previous Redis connection if needed

Why CROSSSLOT errors occur

In a single-node Redis deployment, multi-key commands work without restriction.

In a sharded Redis environment, multi-key commands only succeed when all keys involved map to the same hash slot. If they do not, Redis returns a CROSSSLOT error.

This can affect:

• Sidekiq processes that interact with multiple queue keys

• Application code that uses multi-key commands such as MGET, MSET, SUNION, or SDIFF

• Custom middleware, plugins, or job logic that assumes single-node Redis behavior

Typical symptoms

• CROSSSLOT Keys in request don't hash to the same slot

• Workers stop fetching or processing jobs

• Increased retries or job failures

• Log messages showing MOVED, ASK, or repeated reconnect attempts

• Inconsistent behavior across different worker processes

Step-by-Step Instructions

Step 1: Understand your current Redis usage

Before migrating, review how your application and Sidekiq use Redis.

Focus on:

• Whether workers process multiple queues

• Whether your application uses Redis beyond Sidekiq (caching, locks, scheduling)

• Any use of multi-key Redis commands

• Any Sidekiq plugins or custom logic interacting with Redis

If your workload assumes single-node Redis behavior, plan your migration accordingly.

Step 2: Choose the right migration approach

Select the approach that best fits your workload.

Option A: Match your current behavior (recommended for most cases)
Use a Redis Cloud Pro configuration that behaves similarly to your current deployment. This minimizes the risk of compatibility issues and avoids the need for application changes.

Option B: Use sharded Redis with a cluster-aware workload
If you plan to use a sharded database, ensure your application is compatible:

• Avoid multi-key commands across unrelated keys

• Ensure related keys are structured to work within the same hash slot

• Validate all Redis usage patterns before cutover

Option C: Simplify queue usage during migration
If workers listen to multiple queues, consider simplifying:

• Run workers per queue where possible

• Reduce complexity during migration testing

• Reintroduce more complex patterns after validation

Step 3: Create and configure your Redis Cloud Pro database

Set up your Redis Cloud Pro database before migration.

Validate:

• Memory and throughput sizing

• Security settings (TLS, credentials)

• Network access and connectivity

• That the database behavior matches your chosen migration approach

Step 4: Test in staging

Before production cutover, test your setup in a staging environment.

Validate:

• Job enqueue and processing

• Retries and scheduled jobs

• Worker concurrency behavior

• Any custom Redis usage

Check logs for:

• CROSSSLOT

• MOVED or ASK

• Connection or authentication errors

Do not proceed to production if these errors appear.

Step 5: Perform the cutover

When ready to migrate:

1. Reduce or pause job creation if possible

2. Allow in-flight jobs to complete where appropriate

3. Update your Redis connection environment variables (for example, REDIS_URL)

4. Restart all application components:

   • web processes

   • Sidekiq workers

   • schedulers and background jobs

5. Verify that all components are using the new Redis endpoint

Step 6: Validate after cutover

Immediately after switching:

• Confirm workers are connected and processing jobs

• Check queue latency and job throughput

• Run test jobs to confirm expected behavior

• Monitor logs for errors

Continue monitoring until the system stabilizes under normal load.

Troubleshooting

CROSSSLOT errors after migration

What it means:
Your workload is performing multi-key operations that are not compatible with the current database behavior.

What to do:
Review your Redis usage and adjust your key patterns or workload design. If needed, use a database configuration that matches your original environment more closely.

Workers stop processing jobs

What it means:
Workers may be connected but unable to safely access required Redis keys.

What to do:
Check logs for CROSSSLOT or redirection errors. Validate queue configuration and Redis usage patterns.

Inconsistent behavior across processes

What it means:
Different components may be using different Redis endpoints.

What to do:
Ensure all services were restarted and are using the updated connection settings.

TLS or authentication errors

What it means:
Connection settings do not match the Redis Cloud database configuration.

What to do:
Verify hostname, port, credentials, and TLS usage. Ensure all clients use the correct connection string.

Issues only under production load

What it means:
Some Redis usage patterns only appear at higher concurrency.

What to do:
Analyze logs under load, identify problematic commands, and adjust workload behavior or database configuration.

When to contact Redis Support

Contact Redis Support if:

• You are unsure how your Redis usage may behave after migration

• You rely on Sidekiq plugins or custom Redis logic that is difficult to validate

• You need guidance selecting the safest migration approach

• You encounter persistent errors after following this guide