JuliusBrussee/caveman · error

cachebench: optimize request %q: %w

Error message

cachebench: optimize request %q: %w

What it means

Engine.Optimize returned an error while preparing the record identified by RequestID. The replay runner refuses to send a request it could not optimize, and wraps the engine's error with the request id for correlation.

Source

Thrown at cacheengine/cachebench/replay.go:513

type preparedReplay struct {
	record    TraceRecord
	optimized cacheengine.NativeResult
}

func (runner ReplayRunner) prepare(ctx context.Context, records []TraceRecord) ([]preparedReplay, error) {
	prepared := make([]preparedReplay, 0, len(records))
	for _, record := range records {
		if err := ctx.Err(); err != nil {
			return nil, fmt.Errorf("cachebench: replay preparation interrupted: %w", err)
		}
		native, err := record.NativeRequest()
		if err != nil {
			return nil, err
		}
		optimized, err := runner.Engine.Optimize(ctx, native)
		if err != nil {
			return nil, fmt.Errorf("cachebench: optimize request %q: %w", record.RequestID, err)
		}
		equivalent := bytes.Equal(native.Body, optimized.Body)
		if optimized.Applied {
			equivalent = ModelVisibleEquivalent(native.Body, optimized.Body)
		}
		if !equivalent {
			return nil, &ReplayRunError{
				RequestID: record.RequestID, FailureCode: "model_visible_mismatch",
				Err: fmt.Errorf("cachebench: request %q failed model-visible equivalence", record.RequestID),
			}
		}
		if optimized.Decision != cacheengine.DecisionApply && optimized.Decision != cacheengine.DecisionObserveOnly && optimized.Reason != cacheengine.ReasonBelowMinimum {
			return nil, &ReplayRunError{
				RequestID: record.RequestID, FailureCode: "engine_not_cacheable",
				Err: fmt.Errorf("cachebench: request %q is not cacheable: %s", record.RequestID, optimized.Reason),
			}
		}
		prepared = append(prepared, preparedReplay{record: record, optimized: optimized})

View on GitHub (pinned to 27d5a3981a)

Solutions

1. Unwrap the error (%w chain) and read the underlying engine error — it names the actual cause.
2. Replay the single failing RequestID through Engine.Optimize directly to reproduce in isolation.
3. Check engine initialization (rules/config loaded, backend reachable) before starting the replay.
4. If the record's body is malformed or from an incompatible schema version, re-capture the trace or upgrade the engine.

Example fix

// before
if err := runner.Run(ctx, records, emit); err != nil { log.Fatal(err) } // opaque chain

// after
if err := runner.Run(ctx, records, emit); err != nil {
	var rre *cachebench.ReplayRunError
	if errors.As(err, &rre) {
		log.Printf("request %s failed: %v", rre.RequestID, rre.Err)
	}
	log.Fatal(err)
}

for _, r := range records {
    if _, err := r.NativeRequest(); err != nil {
        return fmt.Errorf("record %s has malformed native request: %w", r.RequestID, err)
    }
}

if err := runner.Run(ctx, records, emit); err != nil {
    var rre *cachebench.ReplayRunError
    if errors.As(err, &rre) {
        log.Printf("request %s: optimize failed: %v", rre.RequestID, errors.Unwrap(err))
    }
    return err
}

When it happens

Trigger: Any cacheengine.Optimize failure during prepare: malformed request body that the engine cannot parse, engine misconfiguration (no rules loaded), engine backend/store errors, or context cancellation surfacing through the engine.

Common situations: Trace bodies recorded against an older API schema than the engine expects; engine initialized without its rule set; a dependency (cache store) down when Optimize consults it; version skew between the trace capture and the engine.

Related errors

• engine_not_cacheable
• cachebench: session %q request %d: %w
• cachebench: observation request %q body digest mismatch
• cachebench: replay request %q has empty provider
• cachebench: provider %q population %d cannot meet minimum el

AI-assisted analysis of JuliusBrussee/caveman@27d5a3981a (2026-08-15). Data as JSON: /api/errors/3577497b13bb14d2. Report an issue: GitHub.