What causes "multiple //go:build comments" in golang/go?

Open the source file and remove all but one //go:build line

multiple //go:build comments

Error message

multiple //go:build comments

What it means

A Go source file contains more than one //go:build constraint comment line. The Go toolchain enforces that each file has at most one //go:build line because multiple constraint lines would create ambiguity in how they combine (AND vs OR). This error is detected during import scanning and build constraint evaluation in the imports package. The sentinel error errMultipleGoBuild is returned.

Source

Thrown at src/cmd/go/internal/imports/build.go:40

	"bytes"
	"cmd/go/internal/cfg"
	"errors"
	"fmt"
	"go/build/constraint"
	"internal/syslist"
	"strings"
	"unicode"
)

var (
	bSlashSlash = []byte("//")
	bStarSlash  = []byte("*/")
	bSlashStar  = []byte("/*")
	bPlusBuild  = []byte("+build")

	goBuildComment = []byte("//go:build")

	errMultipleGoBuild = errors.New("multiple //go:build comments")
)

func isGoBuildComment(line []byte) bool {
	if !bytes.HasPrefix(line, goBuildComment) {
		return false
	}
	line = bytes.TrimSpace(line)
	rest := line[len(goBuildComment):]
	return len(rest) == 0 || len(bytes.TrimSpace(rest)) < len(rest)
}

// ShouldBuild reports whether it is okay to use this file,
// The rule is that in the file's leading run of // comments
// and blank lines, which must be followed by a blank line
// (to avoid including a Go package clause doc comment),
// lines beginning with '// +build' are taken as build directives.
//
// The file is accepted only if each such line lists something

View on GitHub (pinned to b6b368adc5)

Solutions

Open the source file and remove all but one //go:build line
If migrating from // +build to //go:build, ensure only the new syntax remains
Run gofmt -w on the file to normalize comment formatting and detect issues
Use go vet to catch build constraint issues before they cause build failures

Example fix

// before: duplicate build constraints in a Go file
// //go:build linux
// //go:build amd64
// package main

// after: combine into a single constraint
// //go:build linux && amd64
// package main

Defensive patterns

Strategy: validation

Validate before calling

// Scan Go source files for duplicate //go:build comments before building.
import (
    "bufio"
    "os"
    "strings"
)

func checkDuplicateBuildComments(path string) error {
    f, err := os.Open(path)
    if err != nil {
        return err
    }
    defer f.Close()
    scanner := bufio.NewScanner(f)
    count := 0
    for scanner.Scan() {
        line := strings.TrimSpace(scanner.Text())
        if strings.HasPrefix(line, "//go:build") {
            count++
            if count > 1 {
                return fmt.Errorf("%s: multiple //go:build comments", path)
            }
        }
        if strings.HasPrefix(line, "package ") {
            break // build constraints must appear before package clause
        }
    }
    return nil
}

Type guard

// This is a build-time error, not a runtime error.
// No type guard is applicable — the error occurs during compilation/scanning,
// not at runtime. The error is returned as a plain error from the imports scanner.
// Detect by message:
func isMultipleGoBuild(err error) bool {
    return err != nil && strings.Contains(err.Error(), "multiple //go:build comments")
}

Try / catch

// This error occurs during build/list/import scanning, not at runtime.
// It's a source-code error that must be fixed in the file.
// No try-catch is applicable — fix the source.
//
// For tooling that scans Go files:
// err := scanner.ScanFile(path)
// if isMultipleGoBuild(err) {
//     reportToUser("Fix %s: remove duplicate //go:build line", path)
// }

Prevention

Run gofmt -w on all Go files — it normalizes and can detect build constraint issues
When migrating from +build to go:build, use go fix to automate the conversion
Review merge conflict resolutions to ensure build constraints aren't duplicated
Add a pre-commit hook or linting step (golangci-lint) to catch duplicate build tags
When copy-pasting files, check for and update build constraints

When it happens

Trigger: The imports/build.go parser scans a Go source file's leading comments (before the package clause) and encounters more than one line beginning with '//go:build'. isGoBuildComment returns true for multiple lines.

Common situations: Copy-paste error duplicating a build constraint line; merge conflict resolution left duplicate //go:build lines; migration from +build to go:build that added the new tag without removing duplicates; tooling or code generation that auto-inserts build tags without checking for existing ones; manual editing mistake.

Related errors

AI-assisted analysis of golang/go@b6b368adc5 (2026-08-12). Data as JSON: /api/errors/422870a516cc2d21. Report an issue: GitHub.