{"record":{"id":"8f66aa42e5b66c89","repo":"argoproj/argo-workflows","slug":"didn-t-successfully-replace-docs-in-s","errorCode":null,"errorMessage":"Didn't successfully replace docs in %s","messagePattern":"Didn't successfully replace docs in (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"util/telemetry/builder/docs.go","lineNumber":50,"sourceCode":"\tfor i, line := range lines {\n\t\tswitch stage {\n\t\tcase beforeBegin:\n\t\t\tif strings.Contains(line, begin) {\n\t\t\t\tstage = seekingEnd\n\t\t\t\tlines = slices.Insert(lines, i+1, metricsDocsLines(metrics, attribs))\n\t\t\t\tcutfrom = i + 2\n\t\t\t}\n\t\tcase seekingEnd:\n\t\t\tif strings.Contains(line, end) {\n\t\t\t\tstage = finishing\n\t\t\t\tlines = slices.Delete(lines, cutfrom, i+1)\n\t\t\t}\n\t\tcase finishing:\n\t\t\t// Do nothing\n\t\t}\n\t}\n\tif stage != finishing {\n\t\treturn fmt.Errorf(\"Didn't successfully replace docs in %s\", filename)\n\t}\n\n\toutput := strings.Join(lines, \"\\n\")\n\terr = os.WriteFile(filename, []byte(output), 0444)\n\treturn err\n}\n\nfunc createTracingDocs(filename string, spans *spansList, attribs *attributesList) error {\n\t// TODO: AnyParent\n\tinput, err := os.ReadFile(filename)\n\tif err != nil {\n\t\treturn err\n\t}\n\n\tlines := strings.Split(string(input), \"\\n\")\n\n\tconst begin = \"Generated documentation BEGIN\"\n\tconst end = \"Generated documentation END\"","sourceCodeStart":32,"sourceCodeEnd":68,"githubUrl":"https://github.com/argoproj/argo-workflows/blob/35bff19146f5a6ada77468c431f2624bd577e373/util/telemetry/builder/docs.go#L32-L68","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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.","Never hand-edit content inside the generated region of docs/metrics.md; edit generator templates in util/telemetry/builder instead.","Run `make codegen -B` so docs and generator stay in sync.","Diff your docs file against the version the generator was written for if you upgraded the generator."],"exampleFix":"// before: hand-edited doc between markers\n<!-- START ... -->\nmy custom note   <-- breaks state machine\n<!-- END ... -->\n// after\ngit checkout -- docs/metrics.md && make codegen -B","handlingStrategy":"validation","validationCode":"// verify generated markers exist before running the builder\nb, _ := os.ReadFile(\"docs/metrics.md\")\nif !strings.Contains(string(b), \"<!-- START GENERATED DOCUMENTATION\") ||\n   !strings.Contains(string(b), \"END GENERATED DOCUMENTATION\") {\n    return errors.New(\"metrics doc markers missing — restore generated region\")\n}","typeGuard":null,"tryCatchPattern":"if err := createMetricsDocs(...); err != nil {\n    if strings.HasPrefix(err.Error(), \"Didn't successfully replace docs\") {\n        // restore the file from git and rerun codegen\n        exec.Command(\"git\", \"checkout\", \"--\", filename).Run()\n    }\n    return err\n}","preventionTips":["Never hand-edit content between generated doc markers.","Resolve merge conflicts by regenerating docs, not by hand-merging marker regions.","Run make codegen -B after every telemetry change.","Keep marker blocks intact when refactoring docs."],"tags":["codegen","docs","telemetry","metrics"],"backgroundTag":"doc-marker-mismatch","analyzedSha":"35bff19146f5a6ada77468c431f2624bd577e373","analyzedAt":"2026-09-03T19:34:35.908Z","contentChangedAt":"2026-09-03T19:34:35.908Z","schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}