golang/go · error

unknown debug key %s

Error message

unknown debug key %s

What it means

The Go compiler and linker accept `-d` flags for internal debug controls (e.g., `-d=panic`, `-d=nil`, `-d=wb`, `-d=ssa/...`). The flag parser looks up each key in a debug table (`f.tab`) or checks for the `ssa/` prefix for SSA-phase debugging. If neither matches, this error is returned, indicating the debug key name is not recognized by this build of the toolchain.

Source

Thrown at src/cmd/internal/objabi/flag.go:447

			// e.g. -d=ssa/generic_cse/time
			// _ in phase name also matches space
			phase := name[4:]
			flag := "debug" // default flag is debug
			if i := strings.Index(phase, "/"); i >= 0 {
				flag = phase[i+1:]
				phase = phase[:i]
			}
			err := f.debugSSA(phase, flag, val, valstring)
			if err != "" {
				log.Fatal(err)
			}
			// Setting this false for -d=ssa/... preserves old behavior
			// of turning off concurrency for any debug flags.
			// It's not known for sure if this is necessary, but it is safe.
			*f.concurrentOk = false

		} else {
			return fmt.Errorf("unknown debug key %s\n", name)
		}
	}

	return nil
}

const debugHelpHeader = `usage: -d arg[,arg]* and arg is <key>[=<value>]

<key> is one of:

`

func (f *DebugFlag) String() string {
	return ""
}

View on GitHub (pinned to b6b368adc5)

Solutions

1. Run `go tool compile -d help` or `go tool link -d help` to list valid debug keys for your toolchain version.
2. Correct any typos in the key name (e.g., `ssa` not `saa`).
3. Ensure you are using the key with the correct tool — compiler keys differ from linker keys.
4. Upgrade or downgrade Go to the version whose debug keys you need.

Example fix

// before
$ go build -gcflags="-d=saa/generic_cse/time" ./...

// after
$ go build -gcflags="-d=ssa/generic_cse/time" ./...

// list valid keys
$ go tool compile -d help

// List valid debug keys before using them
func getValidDebugKeys(tool string) ([]string, error) {
    cmd := exec.Command(tool, "-d", "help")
    out, err := cmd.CombinedOutput()
    if err != nil {
        return nil, err
    }
    var keys []string
    for _, line := range strings.Split(string(out), "\n") {
        line = strings.TrimSpace(line)
        if line != "" && !strings.HasPrefix(line, "usage") {
            keys = append(keys, line)
        }
    }
    return keys, nil
}

When it happens

Trigger: Passing `-d=unknownkey` to `go build`, `go tool compile`, or `go tool link`. Using a debug key that exists in a different Go version but not in the one currently installed. Misspelling a known debug key like `-d=saa/generic_cse` instead of `-d=ssa/generic_cse`.

Common situations: Following outdated documentation or blog posts that reference debug keys removed in newer Go versions. Typing a debug key name. Running a newer Go toolchain with flags from an older one, or vice versa. Trying to use a compiler debug key on the linker (the two have different debug tables).

Related errors

• invalid count %q
• dwarf: null reference in %d
• failed to locate cmd/compile for target platform
• CC not set and no default found
• local imports disallowed

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