github/github-mcp-server · warning

failed to write README.md: %w

Error message

failed to write README.md: %w

What it means

Returned by generateReadmeDocs when os.WriteFile(readmePath, …, 0600) fails after the README's automated sections were successfully replaced. This is the final persistence step; failure means the process cannot write to README.md at the given path.

Source

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

		return fmt.Errorf("failed to read README.md: %w", err)
	}

	// Replace toolsets section
	updatedContent, err := replaceSection(string(content), "START AUTOMATED TOOLSETS", "END AUTOMATED TOOLSETS", toolsetsDoc)
	if err != nil {
		return err
	}

	// Replace tools section
	updatedContent, err = replaceSection(updatedContent, "START AUTOMATED TOOLS", "END AUTOMATED TOOLS", toolsDoc)
	if err != nil {
		return err
	}

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

	return nil
}

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

	toolsetsDoc := generateRemoteToolsetsDoc()

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

View on GitHub (pinned to 0ea1f775a7)

Solutions

1. Check write permission on the file and its directory (ls -l README.md); chmod u+w README.md or fix ownership
2. If in CI, ensure the checkout step yields writable files (e.g. git config safe.directory / correct USER)
3. Verify the path is a regular file, not a directory, when using a custom flag
4. Free disk space if the volume is full

// Check writability before running the generator
if info, err := os.Stat(readmePath); err == nil {
    if info.Mode().Perm()&0200 == 0 {
        log.Fatalf("%s is not writable", readmePath)
    }
}

if err := generateReadmeDocs(readmePath); err != nil {
    if errors.Is(err, fs.ErrPermission) || strings.Contains(err.Error(), "failed to write README.md") {
        log.Fatalf("cannot write %s — fix permissions (chmod u+w) or CI user", readmePath)
    }
    return err
}

When it happens

Trigger: README.md is owned by another user or marked read-only (no write permission); the path flag points to a directory or an unwritable location; disk full; on some setups, running the generator while an editor/IDE holds an exclusive lock.

Common situations: CI containers running as a non-root user against root-owned checkouts; read-only bind mounts; SELinux/AppArmor denials; running on a branch where README.md permissions were changed.

Related errors

• failed to read README.md: %w
• failed to write deprecated aliases docs: %w
• failed to read docs file: %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/ab8e29957392a73b. Report an issue: GitHub.