DEV Community

侯惠阳
侯惠阳

Posted on • Originally published at houhuiyang.com

A Packaging Bug I Found in Homebrew Redis 8.10.0

#debugging #redis #database #devops

I recently installed Redis 8.10.0 with Homebrew for local development:

brew install redis
brew services start redis
Enter fullscreen mode Exit fullscreen mode

The installation completed normally, and Homebrew reported that the service had started. Its actual state in brew services list, however, was:

redis  error  1
Enter fullscreen mode Exit fullscreen mode

The problem was not that Redis itself could not run. The default configuration shipped in the bottle did not match the files included in that bottle. I reported the bug as Homebrew/homebrew-core#296698. As of August 11, 2026, the issue remains open.

The mismatch

The bottle-provided redis.conf enabled four modules:

loadmodule ./modules/redisbloom/redisbloom.so
loadmodule ./modules/redisearch/redisearch.so
loadmodule ./modules/redisjson/rejson.so
loadmodule ./modules/redistimeseries/redistimeseries.so
Enter fullscreen mode Exit fullscreen mode

The installed bottle contained none of the referenced .so or .dylib files. Redis read the directives, failed to load the missing modules, and exited.

This is an easy failure to misread. “Successfully started” means the service command was submitted; it does not prove that the Redis process remained healthy.

Verifying the cause

I compared the configuration with the installed artifacts:

grep -n "loadmodule.*modules" \
  /opt/homebrew/Cellar/redis/8.10.0/.bottle/etc/redis.conf

find /opt/homebrew/Cellar/redis/8.10.0 \
  -type f \( -name "*.so" -o -name "*.dylib" \)
Enter fullscreen mode Exit fullscreen mode

The first command returned four active loadmodule directives. The second found no corresponding module libraries. That configuration–artifact mismatch was the direct cause.

Temporary workaround

For local development that does not need these modules, the directives can be commented out before restarting Redis:

sed -i '' \
  -e 's|^loadmodule ./modules/|#loadmodule ./modules/|' \
  /opt/homebrew/etc/redis.conf

brew services restart redis
redis-cli ping
Enter fullscreen mode Exit fullscreen mode

After the change, redis-cli ping returned:

PONG
Enter fullscreen mode Exit fullscreen mode

This is a workaround, not an upstream fix. If an application depends on RedisBloom, RediSearch, RedisJSON, or RedisTimeSeries, disabling them is not an acceptable solution. In that case, use a distribution that explicitly includes the required modules or wait for the Homebrew bottle to be corrected.

The practical lesson

When a service fails to start, repeatedly reinstalling or restarting it rarely produces new information. A better sequence is:

  1. Check the real service state and exit code.
  2. Run the process in the foreground and read the direct error.
  3. Compare configuration declarations with installed artifacts.
  4. Make the smallest possible change to verify causality.
  5. Publish a reproducible report for the upstream maintainers.

Open-source contribution does not always begin with a code patch. A focused bug report with clear evidence and reliable reproduction steps can be just as useful.

References

Top comments (0)