What causes "auth: configuration: headers slice is empty" in kataras/iris?

Add at least one entry to Configuration.Headers (e.g. the standard request key)

auth: configuration: headers slice is empty

Error message

auth: configuration: headers slice is empty

What it means

Configuration.validate() rejects configurations whose Headers slice is empty. The auth middleware needs at least one extraction source (request header) to look for tokens, and none was configured.

Source

Thrown at auth/configuration.go:68

		// By setting the secure to true, the web browser will prevent the
		// transmission of a cookie over an unencrypted channel.
		//
		// Defaults to false but it's true when the request is under iris.Context.IsSSL().
		Secure bool `json:"secure" yaml:"Secure" toml:"Secure" ini:"secure"`
		// 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.

View on GitHub (pinned to 7bedaf55a0)

Solutions

Add at least one entry to Configuration.Headers (e.g. the standard request key)
Restore the default header configuration removed by mistake
If only cookies should be used, still configure a header entry — the library requires it

Example fix

// before
Configuration{ Cookie: auth.Cookie{Name: "myapp_session", Hash: h, Block: b} }
// after
Configuration{ Headers: []string{"Authorization"}, Cookie: auth.Cookie{Name: "myapp_session", Hash: h, Block: b} }

Defensive patterns

Strategy: validation

Validate before calling

if len(cfg.Headers) == 0 {
    return errors.New("auth configuration: at least one token extraction header is required")
}

Prevention

Always configure at least one header (e.g. "Authorization" or your request key)
Keep default headers when converting a YAML/TOML config from another project
Add a unit test that constructs Configuration and calls validate() at CI time
Fail fast at startup — validate() errors occur inside auth.New

When it happens

Trigger: Calling auth.New with a Configuration whose Headers field is left as a nil/empty slice — e.g. only a Cookie was configured and Headers was never populated.

Common situations: Copy-pasted config that deleted the default request_key header entry; building Configuration programmatically and forgetting Headers; switching from header-based to cookie-based auth without knowing Headers must remain non-empty.

Related errors

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