kataras/iris · error

auth: configuration: cookie block and cookie hash are requir

Error message

auth: configuration: cookie block and cookie hash are required for security reasons when cookie is used

What it means

When a cookie is configured (Cookie.Name is set), validate() requires both Cookie.Hash and Cookie.Block to be non-empty because cookie values are encrypted/authenticated for security. A half-configured cookie is rejected at startup.

Source

Thrown at auth/configuration.go:73

		// Hash is optional, it is used to authenticate cookie value using HMAC.
		// It is recommended to use a key with 32 or 64 bytes.
		Hash string `json:"hash" yaml:"Hash" toml:"Hash" ini:"hash"`
		// Block is optional, used to encrypt cookie value.
		// The key length must correspond to the block size
		// of the encryption algorithm. For AES, used by default, valid lengths are
		// 16, 24, or 32 bytes to select AES-128, AES-192, or AES-256.
		Block string `json:"block" yaml:"Block" toml:"Block" ini:"block"`
	}
)

func (c *Configuration) validate() (jwt.Keys, error) {
	if len(c.Headers) == 0 {
		return nil, fmt.Errorf("auth: configuration: headers slice is empty")
	}

	if c.Cookie.Name != "" {
		if c.Cookie.Hash == "" || c.Cookie.Block == "" {
			return nil, fmt.Errorf("auth: configuration: cookie block and cookie hash are required for security reasons when cookie is used")
		}
	}

	keys, err := c.Keys.Load()
	if err != nil {
		return nil, fmt.Errorf("auth: configuration: %w", err)
	}

	if _, ok := keys[KIDAccess]; !ok {
		return nil, fmt.Errorf("auth: configuration: %s access token is missing from the configuration", KIDAccess)
	}

	// Let's keep refresh optional.
	// if _, ok := keys[KIDRefresh]; !ok {
	// 	return nil, fmt.Errorf("auth: configuration: %s refresh token is missing from the configuration", KIDRefresh)
	// }
	return keys, nil
}

View on GitHub (pinned to 7bedaf55a0)

Solutions

1. Set both Cookie.Hash and Cookie.Block to strong key material (32-byte keys)
2. Remove the Cookie config entirely if cookies are not used
3. Check the config file keys actually load (case/indentation of yaml/toml/ini tags)
4. Generate keys with crypto/rand rather than hardcoding placeholders

Example fix

// before
Cookie: auth.Cookie{Name: "session"}
// after
Cookie: auth.Cookie{Name: "session", Hash: hashKey(32), Block: blockKey(32)}

if cfg.Cookie.Name != "" && (cfg.Cookie.Hash == "" || cfg.Cookie.Block == "") {
    return errors.New("cookie requires both hash and block keys")
}

func cookieFullyConfigured(c auth.Cookie) bool {
    return c.Name == "" || (c.Hash != "" && c.Block != "")
}

When it happens

Trigger: auth.New with Configuration.Cookie.Name non-empty while Cookie.Hash or Cookie.Block is an empty string.

Common situations: Setting only the cookie name when migrating from header auth to cookie auth; typos in TOML/YAML keys so Hash/Block never load; forgetting that cookies demand AES-GCM-style hash+block keys.

Related errors

• auth: configuration: headers slice is empty
• auth: configuration: %w
• invalid root name
• empty form
• errors joined from param parser: strings.Join(p.errors, "\n"

AI-assisted analysis of kataras/iris@7bedaf55a0 (2026-08-30). Data as JSON: /api/errors/7edad975ad2b7f02. Report an issue: GitHub.