golang/go · error

unknown %s %q

Error message

unknown %s %q

What it means

Thrown by CheckGodebug as the fallthrough error when the key passes space/comma validation, is not 'default', is not found in the known GODEBUG registry (godebugs.Lookup returns nil), and is not in the removed list (godebugs.Removed). The verb parameter is 'godebug' and %q is the unknown key. This means the setting name does not correspond to any recognized GODEBUG setting in this Go version.

Source

Thrown at src/cmd/go/internal/modload/init.go:2316

		}
		if gover.Compare(v[len("go"):], gover.Local()) > 0 {
			return fmt.Errorf("default=%s too new (toolchain is go%s)", v, gover.Local())
		}
		return nil
	}
	if godebugs.Lookup(k) != nil {
		return nil
	}
	for _, info := range godebugs.Removed {
		if info.Name == k {
			if info.Old(v) {
				return fmt.Errorf("removed GODEBUG %q set to old value %q (https://go.dev/doc/godebug#go-1%v)", k, v, info.Removed)
			}
			// Using a removed GODEBUG setting with a non-old value is ok (see go.dev/issue/76163).
			return nil
		}
	}
	return fmt.Errorf("unknown %s %q", verb, k)
}

View on GitHub (pinned to b6b368adc5)

Solutions

1. Check the exact GODEBUG setting name against the official list at https://go.dev/doc/godebug.
2. Correct or remove the misspelled/unknown 'godebug' line in go.mod or go.work.
3. If the setting should exist, upgrade your Go toolchain to a version that supports it.

Example fix

// before
godebug paniconfatl=1  // typo

// after
godebug paniconfatal=1

// Validate a godebug key is known (not unknown) before writing.
// (Requires access to the godebugs registry.)
func validateKnownGodebug(k string) error {
    if k == "default" {
        return nil
    }
    if godebugs.Lookup(k) != nil {
        return nil
    }
    for _, info := range godebugs.Removed {
        if info.Name == k {
            return nil // removed but recognized
        }
    }
    return fmt.Errorf("unknown godebug %q", k)
}

When it happens

Trigger: A go.mod or go.work contains 'godebug typo=1' or references a GODEBUG name that does not exist in the current toolchain's registry. Also occurs if the setting exists only in a newer Go version than the installed toolchain.

Common situations: Typing a GODEBUG setting name incorrectly. Using a setting from a newer Go version on an older toolchain. Keeping stale godebug directives after the setting was renamed or never existed.

Related errors

• key contains space
• value contains space
• key contains comma
• value contains comma
• value for default= must be goVERSION

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