github/github-mcp-server · warning

markers not found: %s / %s

Error message

markers not found: %s / %s

What it means

Returned by replaceSection when the markdown file being rewritten does not contain the expected HTML marker comments (<!-- START … --> / <!-- END … -->) for the section to automate. The generator refuses to guess insertion points: if strings.Cut cannot find the start marker or strings.Index cannot find the end marker, it errors naming both markers. This protects hand-written docs from silent mangling.

Source

Thrown at cmd/github-mcp-server/generate_docs.go:371

	var buf strings.Builder
	lines := strings.Split(description, "\n")
	buf.WriteString(lines[0])
	for i := 1; i < len(lines); i++ {
		buf.WriteString("\n")
		buf.WriteString(indent)
		buf.WriteString(lines[i])
	}
	return buf.String()
}

func replaceSection(content, startMarker, endMarker, newContent string) (string, error) {
	start := fmt.Sprintf("<!-- %s -->", startMarker)
	end := fmt.Sprintf("<!-- %s -->", endMarker)

	before, _, ok := strings.Cut(content, start)
	endIdx := strings.Index(content, end)
	if !ok || endIdx == -1 {
		return "", fmt.Errorf("markers not found: %s / %s", start, end)
	}

	var buf strings.Builder
	buf.WriteString(before)
	buf.WriteString(start)
	buf.WriteString("\n")
	buf.WriteString(newContent)
	buf.WriteString("\n")
	buf.WriteString(content[endIdx:])
	return buf.String(), nil
}

func generateRemoteToolsetsDoc() string {
	var buf strings.Builder

	// Create translation helper
	t, _ := translations.TranslationHelper()

View on GitHub (pinned to 0ea1f775a7)

Solutions

1. Open the named file and restore both marker comments exactly as reported in the error (HTML comments, exact casing)
2. Recover the markers from git history: git log -p -- <file> or git show <rev>:<file>
3. Add the markers to new/custom doc files before running the generator
4. Exclude marker comments from markdown formatter/linter rules that strip HTML comments

Example fix

<!-- before: section header edited away -->
## Toolsets
(list manually maintained)

<!-- after: markers restored verbatim -->
<!-- START AUTOMATED TOOLSETS -->
(generated content)
<!-- END AUTOMATED TOOLSETS -->

// Verify both marker comments exist before running the generator
func hasMarkers(content, startMarker, endMarker string) bool {
    return strings.Contains(content, fmt.Sprintf("<!-- %s -->", startMarker)) &&
        strings.Contains(content, fmt.Sprintf("<!-- %s -->", endMarker))
}
content, _ := os.ReadFile(path)
if !hasMarkers(string(content), "START AUTOMATED TOOLSETS", "END AUTOMATED TOOLSETS") {
    log.Fatalf("%s is missing AUTOMATED markers; restore them from git history", path)
}

updated, err := replaceSection(content, start, end, body)
if err != nil {
    if strings.Contains(err.Error(), "markers not found") {
        // docs drifted: restore the exact marker comments, then re-run
        log.Fatalf("%v — restore the <!-- %s --> / <!-- %s --> comments in the file", err, start, end)
    }
    return err
}

When it happens

Trigger: A human editor deleted, renamed, or retyped the marker comments (e.g. dropped the '!-- … -->' HTML comment syntax or changed capitalization); docs were rewritten by a tool that strips comments; running the generator against a custom doc file that never had the markers; marker text altered by markdown formatters.

Common situations: Docs regenerated in CI after a manual PR restructured the markdown; prettier/markdownlint passes that remove or normalize HTML comments; forks with divergent docs.

Related errors

• failed to read docs file: %w
• failed to generate docs for %s: %w
• failed to read README.md: %w
• failed to write README.md: %w
• failed to read docs file: %w

AI-assisted analysis of github/github-mcp-server@0ea1f775a7 (2026-08-15). Data as JSON: /api/errors/59f768c7d48a8fe3. Report an issue: GitHub.