argoproj/argo-workflows · error

Didn't successfully replace docs in %s

Error message

Didn't successfully replace docs in %s

What it means

createMetricsDocs rewrites the metrics documentation file in-place via a state machine that walks lines until it reaches the 'finishing' stage. If the end of file is reached before the replacement markers were fully consumed (stage != finishing), the doc layout does not match what the generator expects and this error is returned instead of overwriting the file. It is a guard against silently mangling docs/metrics.md.

Source

Thrown at util/telemetry/builder/docs.go:50

	for i, line := range lines {
		switch stage {
		case beforeBegin:
			if strings.Contains(line, begin) {
				stage = seekingEnd
				lines = slices.Insert(lines, i+1, metricsDocsLines(metrics, attribs))
				cutfrom = i + 2
			}
		case seekingEnd:
			if strings.Contains(line, end) {
				stage = finishing
				lines = slices.Delete(lines, cutfrom, i+1)
			}
		case finishing:
			// Do nothing
		}
	}
	if stage != finishing {
		return fmt.Errorf("Didn't successfully replace docs in %s", filename)
	}

	output := strings.Join(lines, "\n")
	err = os.WriteFile(filename, []byte(output), 0444)
	return err
}

func createTracingDocs(filename string, spans *spansList, attribs *attributesList) error {
	// TODO: AnyParent
	input, err := os.ReadFile(filename)
	if err != nil {
		return err
	}

	lines := strings.Split(string(input), "\n")

	const begin = "Generated documentation BEGIN"
	const end = "Generated documentation END"

View on GitHub (pinned to 35bff19146)

Solutions

  1. Restore the generated marker structure in the target docs file (revert docs/metrics.md to committed state: git checkout -- docs/metrics.md) and rerun the builder.
  2. Never hand-edit content inside the generated region of docs/metrics.md; edit generator templates in util/telemetry/builder instead.
  3. Run `make codegen -B` so docs and generator stay in sync.
  4. Diff your docs file against the version the generator was written for if you upgraded the generator.

Example fix

// before: hand-edited doc between markers
<!-- START ... -->
my custom note   <-- breaks state machine
<!-- END ... -->
// after
git checkout -- docs/metrics.md && make codegen -B
Defensive patterns

Strategy: validation

Validate before calling

// verify generated markers exist before running the builder
b, _ := os.ReadFile("docs/metrics.md")
if !strings.Contains(string(b), "<!-- START GENERATED DOCUMENTATION") ||
   !strings.Contains(string(b), "END GENERATED DOCUMENTATION") {
    return errors.New("metrics doc markers missing — restore generated region")
}

Try / catch

if err := createMetricsDocs(...); err != nil {
    if strings.HasPrefix(err.Error(), "Didn't successfully replace docs") {
        // restore the file from git and rerun codegen
        exec.Command("git", "checkout", "--", filename).Run()
    }
    return err
}

Prevention

When it happens

Trigger: Running the telemetry builder (main -> createMetricsDocs) against a docs file whose marker blocks were deleted, renamed, reordered, or hand-edited so the generator never reaches the finishing state.

Common situations: Developers hand-editing the generated docs/metrics.md between the DO-NOT-EDIT markers; docs regenerated from an older release clashing with new markers; reordering sections in the markdown; removing a metric so the marker block shrinks unexpectedly.

Related errors

AI-assisted analysis of argoproj/argo-workflows@35bff19146 (2026-09-03). Data as JSON: /api/errors/8f66aa42e5b66c89. Report an issue: GitHub.