What causes "redis: function stats unexpected key %s" in redis/go-redis?

Upgrade go-redis to the latest v9 release so FUNCTION STATS parsing recognizes all keys your server emits.

redis: function stats unexpected key %s

Error message

redis: function stats unexpected key %s

What it means

Thrown by the FUNCTION STATS reply parser when the stats map contains a key other than `running_script`, `engines`, or `all_running_scripts` (command.go, FunctionStats readReply). An unrecognized top-level key — from a newer server or Redis Enterprise — fails the parse rather than being silently dropped.

Source

Thrown at command.go:6970

	}

	var key string
	var result FunctionStats
	for f := 0; f < n; f++ {
		key, err = rd.ReadString()
		if err != nil {
			return err
		}

		switch key {
		case "running_script":
			result.rs, result.isRunning, err = cmd.readRunningScript(rd)
		case "engines":
			result.Engines, err = cmd.readEngines(rd)
		case "all_running_scripts": // Redis Enterprise only
			result.allrs, result.isRunning, err = cmd.readRunningScripts(rd)
		default:
			return fmt.Errorf("redis: function stats unexpected key %s", key)
		}

		if err != nil {
			return err
		}
	}

	cmd.val = result
	return nil
}

func (cmd *FunctionStatsCmd) readRunningScript(rd *proto.Reader) (RunningScript, bool, error) {
	err := rd.ReadFixedMapLen(3)
	if err != nil {
		if err == Nil {
			return RunningScript{}, false, nil
		}
		return RunningScript{}, false, err

View on GitHub (pinned to c5cad058c7)

Solutions

Upgrade go-redis to the latest v9 release so FUNCTION STATS parsing recognizes all keys your server emits.
Compare the reported key with `redis-cli --raw FUNCTION STATS` output to identify the new field.
Avoid or downgrade FUNCTION STATS on the offending server version until the client is updated.
File a go-redis issue with the raw reply if the key is from a supported Redis version.

Example fix

// before: server emits new FUNCTION STATS key, client unaware
stats, err := client.FunctionStats(ctx) // err: function stats unexpected key foo

// after: upgrade client to parse the extended reply
go get github.com/redis/go-redis/v9@latest

Defensive patterns

Strategy: try-catch

Try / catch

stats, err := rdb.FunctionStats(ctx)
if err != nil {
    if strings.Contains(err.Error(), "function stats unexpected key") {
        // newer/extended server reply: skip stats or upgrade client
        log.Printf("FUNCTION STATS format unsupported: %v", err)
        return nil, errStatsFormat
    }
    return err
}

Prevention

Upgrade go-redis before or together with Redis server upgrades.
Gate FUNCTION STATS calls behind a server-version check (Redis 7.0+).
Verify raw output with `redis-cli FUNCTION STATS` when the error mentions a new key.
Add FUNCTION STATS to CI integration tests to catch format drift early.

When it happens

Trigger: Calling `client.FunctionStats(ctx)` against a server whose FUNCTION STATS reply includes extra top-level fields (e.g. Redis Enterprise forks, newer Redis versions adding stats metadata) that this go-redis version doesn't know.

Common situations: Server/client version drift; Redis Enterprise with extra stats fields; preview Redis builds with evolving FUNCTION STATS format.

Related errors

AI-assisted analysis of redis/go-redis@c5cad058c7 (2026-09-01). Data as JSON: /api/errors/1aa070d70d035bee. Report an issue: GitHub.