gofiber/fiber · error

helmet: HSTSPreloadEnabled requires HSTSExcludeSubdomains…

Error message

helmet: HSTSPreloadEnabled requires HSTSExcludeSubdomains to be false

What it means

helmet rejects the combination HSTSPreloadEnabled=true and HSTSExcludeSubdomains=true. Submission to the HSTS preload list (hstspreload.org) requires includeSubDomains; ExcludeSubdomains is the opposite knob, so enabling both is self-contradictory and would make the site ineligible for preloading. helmet surfaces the inconsistency at construction time.

Solutions

1. If you want preload submission eligibility, set HSTSExcludeSubdomains: false (and keep HSTSPreloadEnabled: true).
2. If you genuinely must exclude subdomains from HSTS, set HSTSPreloadEnabled: false.
3. Audit the config source (env/flags/YAML) that populates both fields so they cannot both be true — encode the constraint at the config layer.

Example fix

// before
app.Use(helmet.New(helmet.Config{
    HSTSPreloadEnabled:    true,
    HSTSExcludeSubdomains: true,
}))

// after — preload requires includeSubDomains
app.Use(helmet.New(helmet.Config{
    HSTSPreloadEnabled:    true,
    HSTSExcludeSubdomains: false,
}))

func validateHelmetPreload(cfg helmet.Config) error {
    if cfg.HSTSPreloadEnabled && cfg.HSTSExcludeSubdomains {
        return errors.New("preload requires includeSubDomains (ExcludeSubdomains=false)")
    }
    return nil
}

if err := validateHelmetPreload(cfg); err != nil {
    log.Fatal(err)
}

When it happens

Trigger: helmet.New(helmet.Config{HSTSPreloadEnabled: true, HSTSExcludeSubdomains: true}). Also reached when both flags are pulled from a feature-flag/config map that was edited without considering their relationship.

Common situations: Enabling preload because a checklist said to, while leaving an old ExcludeSubdomains=true from a previous subdomain-isolation policy; merging two config sources where one sets preload and the other sets exclude; misunderstanding ExcludeSubdomains as 'only apply to apex' rather than 'omit the includeSubDomains directive'.

Related errors

• helmet: HSTSMaxAge must be greater than or equal to 0
• ErrTagInvalid
• ErrUnknownTag
• ErrUpstreamSchemeNotAllowed
• favicon: file size exceeds max bytes

AI-assisted analysis of gofiber/fiber@a105acad6c (2026-08-11). Data as JSON: /api/errors/03c044cb4beb19ef. Report an issue: GitHub.

Appendix: source

Thrown at middleware/helmet/config.go:114

	XPermittedCrossDomain:     "none",
}

// Helper function to set default values
func configDefault(config ...Config) Config {
	// Return default config if nothing provided
	if len(config) < 1 {
		return ConfigDefault
	}

	// Override default config
	cfg := config[0]

	if cfg.HSTSMaxAge < 0 {
		panic("helmet: HSTSMaxAge must be greater than or equal to 0")
	}

	if cfg.HSTSPreloadEnabled && cfg.HSTSExcludeSubdomains {
		panic("helmet: HSTSPreloadEnabled requires HSTSExcludeSubdomains to be false")
	}

	// Set default values
	if cfg.XSSProtection == "" {
		cfg.XSSProtection = ConfigDefault.XSSProtection
	}

	if cfg.ContentTypeNosniff == "" {
		cfg.ContentTypeNosniff = ConfigDefault.ContentTypeNosniff
	}

	if cfg.XFrameOptions == "" {
		cfg.XFrameOptions = ConfigDefault.XFrameOptions
	}

	if cfg.ReferrerPolicy == "" {
		cfg.ReferrerPolicy = ConfigDefault.ReferrerPolicy
	}

View on GitHub (pinned to a105acad6c)