github/github-mcp-server · warning

failed to write deprecated aliases docs: %w

Error message

failed to write deprecated aliases docs: %w

What it means

Returned by generateDeprecatedAliasesDocs when the final os.WriteFile(docsPath, …, 0600) fails after successfully rebuilding the deprecated-aliases table between the markers. The generation logic completed; only persisting docs/tool-renaming.md failed.

Source

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

	// Read the current file
	content, err := os.ReadFile(docsPath) //#nosec G304
	if err != nil {
		return fmt.Errorf("failed to read docs file: %w", err)
	}

	// Generate the table
	aliasesDoc := generateDeprecatedAliasesTable()

	// Replace content between markers
	updatedContent, err := replaceSection(string(content), "START AUTOMATED ALIASES", "END AUTOMATED ALIASES", aliasesDoc)
	if err != nil {
		return err
	}

	// Write back to file
	err = os.WriteFile(docsPath, []byte(updatedContent), 0600)
	if err != nil {
		return fmt.Errorf("failed to write deprecated aliases docs: %w", err)
	}

	return nil
}

func generateDeprecatedAliasesTable() string {
	var buf strings.Builder

	// Add table header
	buf.WriteString("| Old Name | New Name |\n")
	buf.WriteString("|----------|----------|\n")

	aliases := github.DeprecatedToolAliases
	if len(aliases) == 0 {
		buf.WriteString("| *(none currently)* | |")
	} else {
		// Sort keys for deterministic output
		var oldNames []string

View on GitHub (pinned to 0ea1f775a7)

Solutions

1. Ensure write permission on docs/tool-renaming.md (chmod u+w or fix ownership)
2. In CI, make the checkout writable or run the docs job as the owning user
3. Confirm the path targets a regular file on a writable volume

if info, err := os.Stat(docsPath); err == nil && info.Mode().Perm()&0200 == 0 {
    log.Fatalf("%s is read-only; chmod u+w before generating docs", docsPath)
}

if err := generateDeprecatedAliasesDocs(docsPath); err != nil {
    if errors.Is(err, fs.ErrPermission) || strings.Contains(err.Error(), "failed to write deprecated aliases docs") {
        log.Fatalf("cannot write %s — fix ownership/permissions or the CI user", docsPath)
    }
    return err
}

When it happens

Trigger: docs/tool-renaming.md (or the flag-provided path) is not writable: root-owned file in a CI container, read-only mount, directory in place of the file, or full disk.

Common situations: CI running as non-root against root-owned checkout; read-only bind mounts in containers; local runs where the file was chmod'ed 444.

Related errors

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

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