golang/go · error

unknown

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.

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 comma
• key contains space
• value contains comma
• value contains space
• 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.

Appendix: 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)