gin-gonic/gin · critical

gin mode unknown: ${value} (available mode: debug release te

Error message

gin mode unknown: ${value} (available mode: debug release test)

What it means

SetMode (mode.go:75) panics with this message when the supplied mode string (or the GIN_MODE env var, read in init()) is not one of debug/release/test. Because init() calls SetMode(os.Getenv("GIN_MODE")), a bad GIN_MODE value panics at program startup before main runs.

Source

Thrown at mode.go:75

// SetMode sets gin mode according to input string.
func SetMode(value string) {
	if value == "" {
		if flag.Lookup("test.v") != nil {
			value = TestMode
		} else {
			value = DebugMode
		}
	}

	switch value {
	case DebugMode:
		atomic.StoreInt32(&ginMode, debugCode)
	case ReleaseMode:
		atomic.StoreInt32(&ginMode, releaseCode)
	case TestMode:
		atomic.StoreInt32(&ginMode, testCode)
	default:
		panic("gin mode unknown: " + value + " (available mode: debug release test)")
	}
	modeName.Store(value)
}

// DisableBindValidation closes the default validator.
func DisableBindValidation() {
	binding.Validator = nil
}

// EnableJsonDecoderUseNumber sets true for binding.EnableDecoderUseNumber to
// call the UseNumber method on the JSON Decoder instance.
func EnableJsonDecoderUseNumber() {
	binding.EnableDecoderUseNumber = true
}

// EnableJsonDecoderDisallowUnknownFields sets true for binding.EnableDecoderDisallowUnknownFields to
// call the DisallowUnknownFields method on the JSON Decoder instance.
func EnableJsonDecoderDisallowUnknownFields() {

View on GitHub (pinned to 34dac209ff)

Solutions

1. Use exactly one of: debug, release, test (case-sensitive, lowercase). For production use GIN_MODE=release.
2. Unset GIN_MODE (or pass "") to fall back to debug (or test when running under `go test -v`).
3. If you set the mode in code, call gin.SetMode(gin.ReleaseMode) using the constant, not a literal.

Example fix

// before
# Dockerfile
ENV GIN_MODE=production
// after
ENV GIN_MODE=release

switch os.Getenv(gin.EnvGinMode) {
case "", gin.DebugMode, gin.ReleaseMode, gin.TestMode:
    // ok
default:
    log.Fatalf("GIN_MODE=%q is invalid; use one of debug|release|test", os.Getenv(gin.EnvGinMode))
}

When it happens

Trigger: Setting GIN_MODE=production (should be release) in the environment or Dockerfile; calling gin.SetMode("PROD") with wrong case or spelling; importing gin in a binary whose env exports GIN_MODE=Release.

Common situations: Container/Dockerfile ENV GIN_MODE=production (common mistake — the release value is "release"); CI config that upper-cases the value; copy-paste from docs that say "production mode".

Related errors

• the HTML debug render was created without files or glob patt
• http method ${httpMethod} is not valid
• URL parameters can not be used when serving a static file
• URL parameters can not be used when serving a static folder
• key %v does not exist

AI-assisted analysis of gin-gonic/gin@34dac209ff (2026-08-04). Data as JSON: /data/errors/4915bfc60bdd1ab1.json. Report an issue: GitHub.