old_string matched %d times. Include more surrounding contex

Error message

old_string matched %d times. Include more surrounding context so it is unique, or set replace_all=true

What it means

applySandboxEdit throws this when old_string matches the file content more than once (strings.Count > 1) and replaceAll is false. Because an ambiguous match could edit the wrong location, the tool refuses the edit and asks for more context or explicit replace-all semantics.

Source

Thrown at internal/agent/tools/sandbox_edit.go:288

func (t *EditSandboxFileTool) Cleanup(ctx context.Context) error {
	return nil
}

// applySandboxEdit performs an exact string replacement. replaceAll=false
// requires a unique match.
func applySandboxEdit(content, oldString, newString string, replaceAll bool) (string, int, error) {
	if oldString == "" {
		return "", 0, fmt.Errorf("old_string is required; copy the exact text to change, including whitespace")
	}
	if oldString == newString {
		return "", 0, fmt.Errorf("old_string and new_string are identical; no change would be made")
	}
	n := strings.Count(content, oldString)
	if n == 0 {
		return "", 0, fmt.Errorf("old_string was not found in the file. Copy the exact text (including whitespace) from the file")
	}
	if n > 1 && !replaceAll {
		return "", 0, fmt.Errorf(
			"old_string matched %d times. Include more surrounding context so it is unique, or set replace_all=true",
			n,
		)
	}
	if replaceAll {
		return strings.ReplaceAll(content, oldString, newString), n, nil
	}
	return strings.Replace(content, oldString, newString, 1), 1, nil
}

View on GitHub (pinned to 988cbb0330)

Solutions

Expand old_string with more surrounding lines so it matches exactly one location in the file.
Set replace_all=true if you intentionally want every occurrence replaced.
Search the file for the snippet first to see how many places it appears and pick a unique anchor.

Example fix

// before: ambiguous
applySandboxEdit(content, "return nil", "return err", false)
// after: unique context
applySandboxEdit(content, "func Foo() error {\n\treturn nil\n}", "func Foo() error {\n\treturn err\n}", false)

Defensive patterns

Strategy: validation

Validate before calling

if strings.Count(fileContent, oldString) > 1 && !replaceAll {
    return fmt.Errorf("old_string is ambiguous; add context or set replace_all")
}

Try / catch

newContent, n, err := applySandboxEdit(content, oldString, newString, replaceAll)
if err != nil && strings.Contains(err.Error(), "matched") {
    oldString = widenWithSurroundingContext(path, oldString) // retry with more context
    newContent, n, err = applySandboxEdit(content, oldString, newString, replaceAll)
}

Prevention

Include distinctive surrounding lines (function signature, unique identifiers) in old_string.
Check strings.Count(content, oldString) == 1 before calling unless replaceAll is intended.
Never use tiny generic snippets like braces or single lines as anchors.

When it happens

Trigger: Calling Execute with a short or repeated old_string (e.g. a closing brace, a common import line, a repeated boilerplate block) without setting replace_all=true.

Common situations: Editing repeated function signatures, imports, log lines, or closing brackets; refactoring patterns that occur in multiple places; selecting too small a snippet around a common pattern.

Related errors

AI-assisted analysis of Tencent/WeKnora@988cbb0330 (2026-09-02). Data as JSON: /api/errors/291fa4ac7e7ecda5. Report an issue: GitHub.