JuliusBrussee/caveman · critical

unsafe recovery failure result: %w

Error message

unsafe recovery failure result: %w

What it means

Emitted by the caveman-engine CLI when compression (CCR) failed AND the engine's result contradicts the byte-safety contract: on a CCR failure the engine must return an accounted pass-through (output == input, PassedThrough() true, token counts unchanged). A contradictory result means the fallback path itself is broken, so the CLI refuses to emit possibly-wrong bytes and fails instead of guessing.

Source

Thrown at engine/cmd/caveman-engine/main.go:125

	if err := emitCompressResult(input, res, err, os.Stdout, os.Stderr); err != nil {
		fatal("compress: %v", err)
	}
}

type compressReport struct {
	engine.Result
	Error string `json:"error,omitempty"`
}

// emitCompressResult preserves the engine's byte-safety contract at the CLI
// boundary. CCR failures are expected operational conditions: the engine has
// already returned an accounted pass-through result, so stdout must still get
// the original bytes. Any contradictory result fails rather than guessing.
func emitCompressResult(input []byte, res engine.Result, compressErr error, stdout, stderr io.Writer) error {
	code := ""
	if compressErr != nil {
		if !bytes.Equal(res.Output, input) || !res.PassedThrough() || res.TokensAfter != res.TokensBefore {
			return fmt.Errorf("unsafe recovery failure result: %w", compressErr)
		}
		code = "cave_ccr_unavailable"
		if errors.Is(compressErr, ccr.ErrBudgetExceeded) {
			code = "cave_ccr_budget_exceeded"
		}
	}
	if _, err := stdout.Write(res.Output); err != nil {
		return fmt.Errorf("write stdout: %w", err)
	}
	// Report stays on stderr so stdout remains clean payload bytes.
	report, err := json.Marshal(compressReport{Result: res, Error: code})
	if err != nil {
		return fmt.Errorf("encode report: %w", err)
	}
	if _, err := fmt.Fprintln(stderr, string(report)); err != nil {
		return fmt.Errorf("write report: %w", err)
	}
	return nil

View on GitHub (pinned to 27d5a3981a)

Solutions

1. Note the wrapped compressErr — it identifies which CCR failure started the fallback.
2. Reinstall/rebuild the engine binary so the CLI and engine packages come from one consistent build.
3. If reproducible with a small input, file a bug: this error indicates an internal invariant violation, not user misconfiguration.
4. As a workaround, run with the CCR store disabled or a fresh store path so the failing CCR path is bypassed.

// In shell: this error means exit non-zero; do NOT reuse partial stdout
// out, err := cmd.Output(); if err != nil { discard out entirely }

When it happens

Trigger: Running `caveman-engine compress` (or equivalent subcommand) where the engine returns an error from Compress but the accompanying Result is not byte-identical to the input or reports changed token counts — i.e. an engine-internal invariant break or a version mismatch between the CLI and the engine package.

Common situations: A bug in the engine's error-recovery path; an engine package built/patched inconsistently with the CLI; corrupted intermediate state after a crash mid-compress.

Related errors

• target already exists: ${path}
• cave_harness_request_invalid
• cave_eve_terminal_${result.status}
• cave_retry_accounting_invalid
• cave_budget_reservation_double_settle

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