caddyserver/caddy · error

cache capacity must be >= 0

Error message

cache capacity must be >= 0

What it means

tls.cache.capacity is the certificate cache size limit where 0 means unlimited and positive values bound the cache; negative values are meaningless. Validate() rejects a negative capacity outright.

Source

Thrown at modules/caddytls/tls.go:394

		hostSet := make(map[string]int)
		for i, ap := range t.Automation.Policies {
			if len(ap.subjects) == 0 {
				if hasDefault {
					return fmt.Errorf("automation policy %d is the second policy that acts as default/catch-all, but will never be used", i)
				}
				hasDefault = true
			}
			for _, h := range ap.subjects {
				if first, ok := hostSet[h]; ok {
					return fmt.Errorf("automation policy %d: cannot apply more than one automation policy to host: %s (first match in policy %d)", i, h, first)
				}
				hostSet[h] = i
			}
		}
	}
	if t.Cache != nil {
		if t.Cache.Capacity < 0 {
			return fmt.Errorf("cache capacity must be >= 0")
		}
	}
	return nil
}

// Start activates the TLS module.
func (t *TLS) Start() error {
	// warn if on-demand TLS is enabled but no restrictions are in place
	if t.Automation.OnDemand == nil || (t.Automation.OnDemand.Ask == "" && t.Automation.OnDemand.permission == nil) {
		for _, ap := range t.Automation.Policies {
			if ap.OnDemand && ap.isWildcardOrDefault() {
				if c := t.logger.Check(zapcore.WarnLevel, "YOUR SERVER MAY BE VULNERABLE TO ABUSE: on-demand TLS is enabled, but no protections are in place"); c != nil {
					c.Write(zap.String("docs", "https://caddyserver.com/docs/automatic-https#on-demand-tls"))
				}
				break
			}
		}
	}

View on GitHub (pinned to 50e54ee279)

Solutions

1. Set capacity to a positive number to bound the cache, or 0/omit for unlimited
2. If the intent was unlimited, just remove the cache block

Example fix

// before
"cache": {"capacity": -1}
// after
"cache": {"capacity": 0}

if tlsApp.Cache != nil && tlsApp.Cache.Capacity < 0 {
	return fmt.Errorf("cert cache capacity must be >= 0")
}

When it happens

Trigger: JSON config with {"cache": {"capacity": -10}} under the tls app; Caddyfile global option 'cert_cache -10'. Zero is allowed (unlimited), so any negative number is the trigger.

Common situations: Users attempting to 'disable' the cache with -1; arithmetic in generated configs producing negative numbers; misunderstanding that 0 already means unlimited.

Related errors

• automation policy %d is the second policy that acts as defau
• parsing listener address: %v
• must be exactly one listener address; cannot listen on: %s
• indexing config: %v
• %s: %s field must be a string or number

AI-assisted analysis of caddyserver/caddy@50e54ee279 (2026-08-15). Data as JSON: /api/errors/718e0827132195b6. Report an issue: GitHub.