{"record":{"id":"396959491b1dd01f","repo":"caddyserver/caddy","slug":"applying-global-server-options-v","errorCode":null,"errorMessage":"applying global server options: %v","messagePattern":"applying global server options: (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"caddyconfig/httpcaddyfile/httptype.go","lineNumber":1113,"sourceCode":"\t\t\t(len(srv.TLSConnPolicies) > 0 || !autoHTTPSWillAddConnPolicy || defaultSNI != \"\" || fallbackSNI != \"\") {\n\t\t\tsrv.TLSConnPolicies = append(srv.TLSConnPolicies, &caddytls.ConnectionPolicy{\n\t\t\t\tDefaultSNI:  defaultSNI,\n\t\t\t\tFallbackSNI: fallbackSNI,\n\t\t\t})\n\t\t}\n\n\t\t// tidy things up a bit\n\t\tsrv.TLSConnPolicies, err = consolidateConnPolicies(srv.TLSConnPolicies)\n\t\tif err != nil {\n\t\t\treturn nil, fmt.Errorf(\"consolidating TLS connection policies for server %d: %v\", i, err)\n\t\t}\n\t\tsrv.Routes = consolidateRoutes(srv.Routes)\n\n\t\tservers[fmt.Sprintf(\"srv%d\", i)] = srv\n\t}\n\n\tif err := applyServerOptions(servers, options, warnings); err != nil {\n\t\treturn nil, fmt.Errorf(\"applying global server options: %v\", err)\n\t}\n\n\treturn servers, nil\n}\n\n// sniNames returns the server names a connection policy's sni matcher matches.\n// The bool is false when the policy has no sni matcher, or when it does not\n// decode - the latter is unexpected enough to warn about rather than silently\n// skip, since callers use it to decide whether a hostname needs shielding.\nfunc sniNames(cp *caddytls.ConnectionPolicy, what string, warnings *[]caddyconfig.Warning) ([]string, bool) {\n\traw, ok := cp.MatchersRaw[\"sni\"]\n\tif !ok {\n\t\treturn nil, false\n\t}\n\tvar sni caddytls.MatchServerName\n\tif err := json.Unmarshal(raw, &sni); err != nil {\n\t\t*warnings = append(*warnings, caddyconfig.Warning{\n\t\t\tMessage: fmt.Sprintf(\"decoding sni matcher %swhile checking wildcard coverage: %v\", what, err),","sourceCodeStart":1095,"sourceCodeEnd":1131,"githubUrl":"https://github.com/caddyserver/caddy/blob/50e54ee279aa1e504fe218ca49ab6ae16c100410/caddyconfig/httpcaddyfile/httptype.go#L1095-L1131","documentation":"Raised when applyServerOptions fails while applying Caddyfile global options (e.g. `servers`, `grace_period`, `shutdown_delay`, `timeouts`, `max_header_size`, `trusted_proxies`, `metrics`) to the generated set of HTTP servers. The original error from the option parser is wrapped with 'applying global server options'.","triggerScenarios":"Calling the Caddyfile adapter with a global `servers` block containing an invalid subdirective or bad value (e.g. `servers { read_timeout notanumber }`), an unknown protocol name in `protocols h3`, invalid `trusted_proxies` CIDR, or a listener address string that cannot be parsed — all of which make applyServerOptions return an error after the servers map was built.","commonSituations":"Upgrading Caddy versions where global server option names changed (e.g. older `max_header_size` moved under `servers`), typos in the global options block, or programmatically invoking caddyfile.ServerType.Setup with an options map missing required values.","solutions":["Read the wrapped error text — it names the exact option and reason; fix that token in the global options block","Verify the option exists in your Caddy version (check `caddy adapt` against current docs)","If adapting programmatically, validate option values before calling Setup","Remove the offending subdirective and re-adapt to isolate it"],"exampleFix":"# before\n{\n  servers {\n    read_timeout notanumber\n  }\n}\n# after\n{\n  servers {\n    read_timeout 30s\n  }\n}","handlingStrategy":"validation","validationCode":"// Programmatically: validate global option values before calling ServerType.Setup\nif v, ok := options[\"servers\"]; ok {\n    if _, ok := v.(string); !ok { return fmt.Errorf(\"servers option malformed\") }\n}","typeGuard":null,"tryCatchPattern":"out, warn, err := caddyfile.Adapt(cfg, map[string]any{\"filename\":\"Caddyfile\"})\nif err != nil {\n    return fmt.Errorf(\"adapt failed (check global options block): %w\", err)\n}","preventionTips":["Keep global options minimal and version-checked","After upgrading Caddy, re-run caddy adapt before reload","Use `caddy validate --config Caddyfile` in deployment scripts"],"tags":["caddy","caddyfile","global-options","config"],"backgroundTag":null,"analyzedSha":"50e54ee279aa1e504fe218ca49ab6ae16c100410","analyzedAt":"2026-08-15T09:20:21.641Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}