The Problem

Redis fails to load external modules with errors like:

bash
Module /usr/lib/redis/modules/mymodule.so not found
Module /usr/lib/redis/modules/mymodule.so failed to load: Module initialization failed
Module command not allowed under ACL

Modules extend Redis functionality but require proper configuration and compatibility.

Understanding Redis Modules

Redis modules are dynamically loaded shared libraries (.so files) that: - Add new commands - Implement new data types - Extend Redis capabilities

Common modules: - RedisJSON - JSON data type - RedisSearch - Full-text search - RedisGraph - Graph database - RedisTimeSeries - Time series data - RedisBloom - Bloom filters

Diagnosis Commands

Check Loaded Modules

bash
redis-cli MODULE LIST

Output:

bash
1) 1) "name"
   2) "json"
   3) "ver"
   4) 20000
2) 1) "name"
   2) "search"
   3) "ver"
   4) 20304

Attempt Module Load

bash
redis-cli MODULE LOAD /path/to/module.so

Check Module Directory

bash
ls -la /usr/lib/redis/modules/

Check Redis Configuration

bash
redis-cli CONFIG GET loadmodule

Common Module Loading Errors

Error 1: Module File Not Found

bash
Module /usr/lib/redis/modules/mymodule.so not found

Diagnosis:

```bash # Check if file exists ls -la /usr/lib/redis/modules/mymodule.so

# Check Redis user can read it sudo -u redis cat /usr/lib/redis/modules/mymodule.so >/dev/null && echo "Readable" || echo "Not readable" ```

Solution:

  1. 1.Find correct module path:
bash
find / -name "module_name.so" 2>/dev/null
  1. 1.Copy module to correct location:
bash
sudo cp module_name.so /usr/lib/redis/modules/
sudo chown redis:redis /usr/lib/redis/modules/module_name.so
sudo chmod 755 /usr/lib/redis/modules/module_name.so
  1. 1.Load with correct path:
bash
redis-cli MODULE LOAD /usr/lib/redis/modules/module_name.so

Error 2: Permission Denied

bash
Module /usr/lib/redis/modules/mymodule.so failed to load: Permission denied

Diagnosis:

bash
ls -la /usr/lib/redis/modules/mymodule.so

Solution:

```bash # Fix permissions sudo chown redis:redis /usr/lib/redis/modules/mymodule.so sudo chmod 755 /usr/lib/redis/modules/mymodule.so

# Verify Redis can load it sudo -u redis redis-cli MODULE LOAD /usr/lib/redis/modules/mymodule.so ```

Error 3: Module Initialization Failed

bash
Module initialization failed

Diagnosis:

```bash # Check Redis logs grep -i "module" /var/log/redis/redis-server.log | tail -20

# Check module version compatibility redis-cli INFO server | grep redis_version ```

Common Causes:

  1. 1.Version mismatch:
bash
# Module requires specific Redis version
# Check module documentation for requirements
  1. 1.Missing dependencies:
bash
# Check shared library dependencies
ldd /usr/lib/redis/modules/mymodule.so

Missing libraries output:

bash
libssl.so.1.1 => not found
libcrypto.so.1.1 => not found

Solution:

Install missing dependencies:

```bash # Ubuntu/Debian sudo apt-get install libssl-dev

# CentOS/RHEL sudo yum install openssl-devel ```

  1. 1.Configuration conflicts:
bash
# Check if module requires specific config
redis-cli CONFIG GET "*"

Error 4: Module Already Loaded

bash
Module already loaded

Diagnosis:

bash
redis-cli MODULE LIST

Solution:

Unload before reloading (if module supports unload):

bash
redis-cli MODULE UNLOAD mymodule
redis-cli MODULE LOAD /usr/lib/redis/modules/mymodule.so

Not all modules support unload. Restart Redis if unload fails:

bash
sudo systemctl restart redis-server

Error 5: ACL Blocks Module Command

bash
Module command not allowed under ACL

Diagnosis:

```bash # Check ACL rules redis-cli ACL LIST

# Check current user permissions redis-cli ACL WHOAMI redis-cli ACL GETUSER default ```

Solution:

Grant module command permissions:

```bash # Allow all module commands redis-cli ACL SETUSER default +@module

# Or allow specific module commands redis-cli ACL SETUSER default +module.load +module.unload +module.list ```

Error 6: Symbol Not Found

bash
Error loading module: symbol not found: some_function

Diagnosis:

```bash # Check module exports nm -D /usr/lib/redis/modules/mymodule.so | grep some_function

# Check Redis version (module API may have changed) redis-cli INFO server | grep redis_version ```

Solution:

Module is incompatible with current Redis version. Options:

  1. 1.Update Redis to compatible version
  2. 2.Use older module version matching your Redis
  3. 3.Contact module author for compatibility fix

Error 7: Module Load in Configuration

Modules defined in redis.conf fail to load at startup.

Diagnosis:

bash
grep loadmodule /etc/redis/redis.conf

Common Issue: Module path is wrong in config file.

Solution:

Correct the path in redis.conf:

```conf # Old (wrong path) loadmodule /modules/mymodule.so

# New (correct path) loadmodule /usr/lib/redis/modules/mymodule.so ```

Or pass module args correctly:

conf
loadmodule /usr/lib/redis/modules/rejson.so
loadmodule /usr/lib/redis/modules/redisearch.so WITHCURSORS

Module-Specific Troubleshooting

RedisJSON

```bash # Load RedisJSON redis-cli MODULE LOAD /usr/lib/redis/modules/rejson.so

# Test redis-cli JSON.SET myjson $ '{"name":"test"}' redis-cli JSON.GET myjson ```

Common issues: - Requires Redis 5.0+ - JSON.SET syntax errors (use $ for root path)

RedisSearch

```bash # Load RedisSearch redis-cli MODULE LOAD /usr/lib/redis/modules/redisearch.so

# Test redis-cli FT.CREATE myindex ON HASH PREFIX 1 doc: SCHEMA title TEXT ```

Common issues: - Index creation syntax - Requires sufficient memory - WITHCURSORS option for large result sets

RedisGraph

```bash # Load RedisGraph redis-cli MODULE LOAD /usr/lib/redis/modules/redisgraph.so

# Test redis-cli GRAPH.QUERY mygraph "CREATE (:person {name:'Alice'})" ```

Common issues: - Cypher syntax differences from Neo4j - Graph size limitations

Configuration for Modules

In redis.conf

```conf # Load modules at startup loadmodule /usr/lib/redis/modules/rejson.so loadmodule /usr/lib/redis/modules/redisearch.so loadmodule /usr/lib/redis/modules/redistimeseries.so

# Module directory (for module commands) # Some modules read from this # module-dir /usr/lib/redis/modules/ ```

With Command Line

bash
# Start Redis with modules
redis-server --loadmodule /usr/lib/redis/modules/rejson.so \
             --loadmodule /usr/lib/redis/modules/redisearch.so

Docker with Modules

```bash # Using Redis with modules in Docker docker run -p 6379:6379 \ -v /path/to/modules:/modules \ redis/redis-stack-server:latest

# Or mount and load docker run -p 6379:6379 redis:latest \ --loadmodule /modules/rejson.so ```

Dependency Resolution

Check Module Dependencies

bash
ldd /usr/lib/redis/modules/mymodule.so

Output:

bash
linux-vdso.so.1 =>  (0x00007ffcc9bfe000)
libc.so.6 => /lib/x86_64-linux-gnu/libc.so.6 (0x00007f8a3a600000)
/lib64/ld-linux-x86-64.so.2 (0x00007f8a3aa00000)

If "not found" appears, install the missing library.

Common Dependencies

```bash # Install common dependencies

# Ubuntu/Debian sudo apt-get update sudo apt-get install -y build-essential python3-dev libssl-dev libffi-dev

# CentOS/RHEL sudo yum groupinstall "Development Tools" sudo yum install python3-devel openssl-devel libffi-devel ```

Monitoring Module Status

Check Module Health

```bash #!/bin/bash # Check all expected modules are loaded

EXPECTED_MODULES="json search timeseries"

for module in $EXPECTED_MODULES; do if redis-cli MODULE LIST | grep -q "\"$module\""; then echo "OK: $module loaded" else echo "FAIL: $module not loaded" # Attempt to load redis-cli MODULE LOAD /usr/lib/redis/modules/${module}.so fi done ```

Module Version Check

bash
redis-cli MODULE LIST | while read line; do
    if [[ $line =~ \"name\" ]]; then
        read name_line
        read ver_line
        name=$(echo "$name_line" | sed 's/.*"\([^"]*\)".*/\1/')
        ver=$(echo "$ver_line" | awk '{print $2}')
        echo "Module: $name Version: $ver"
    fi
done

Verification

After loading modules:

```bash # List all modules redis-cli MODULE LIST

# Test module command (example for RedisJSON) redis-cli JSON.SET test $ '{"test":true}' redis-cli JSON.GET test

# Test module command (example for RedisSearch) redis-cli FT.CREATE testidx SCHEMA txt TEXT redis-cli FT.ADD testidx doc1 1.0 FIELDS txt "hello world" redis-cli FT.SEARCH testidx "hello" ```

Restart with Modules

If modules need to be loaded at startup:

```bash # Add to redis.conf sudo tee -a /etc/redis/redis.conf <<EOF loadmodule /usr/lib/redis/modules/rejson.so loadmodule /usr/lib/redis/modules/redisearch.so EOF

# Restart Redis sudo systemctl restart redis-server

# Verify modules loaded redis-cli MODULE LIST ```