{"record":{"id":"6720a7c0a957f7ad","repo":"caddyserver/caddy","slug":"provisioning-header-operations-v","errorCode":null,"errorMessage":"provisioning header operations: %v","messagePattern":"provisioning header operations: (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"modules/caddyhttp/push/handler.go","lineNumber":70,"sourceCode":"\n\tlogger *zap.Logger\n}\n\n// CaddyModule returns the Caddy module information.\nfunc (Handler) CaddyModule() caddy.ModuleInfo {\n\treturn caddy.ModuleInfo{\n\t\tID:  \"http.handlers.push\",\n\t\tNew: func() caddy.Module { return new(Handler) },\n\t}\n}\n\n// Provision sets up h.\nfunc (h *Handler) Provision(ctx caddy.Context) error {\n\th.logger = ctx.Logger()\n\tif h.Headers != nil {\n\t\terr := h.Headers.Provision(ctx)\n\t\tif err != nil {\n\t\t\treturn fmt.Errorf(\"provisioning header operations: %v\", err)\n\t\t}\n\t}\n\treturn nil\n}\n\nfunc (h Handler) ServeHTTP(w http.ResponseWriter, r *http.Request, next caddyhttp.Handler) error {\n\tpusher, ok := w.(http.Pusher)\n\tif !ok {\n\t\treturn next.ServeHTTP(w, r)\n\t}\n\n\t// short-circuit recursive pushes\n\tif _, ok := r.Header[pushHeader]; ok {\n\t\treturn next.ServeHTTP(w, r)\n\t}\n\n\trepl := r.Context().Value(caddy.ReplacerCtxKey).(*caddy.Replacer)\n\tserver := r.Context().Value(caddyhttp.ServerCtxKey).(*caddyhttp.Server)","sourceCodeStart":52,"sourceCodeEnd":88,"githubUrl":"https://github.com/caddyserver/caddy/blob/50e54ee279aa1e504fe218ca49ab6ae16c100410/modules/caddyhttp/push/handler.go#L52-L88","documentation":"During provisioning of the HTTP/2 server push handler, its nested HeaderConfig (header add/set/delete operations applied to push requests) failed to provision. This is a wrapper error; the underlying cause comes from headers.HeaderConfig.Provision, typically a placeholder that cannot be resolved or an invalid header-operation definition.","triggerScenarios":"Configuring 'push' with a 'headers' block whose sub-operations (add/set/delete/replace) contain invalid header names, malformed regex replacements, or placeholders that fail to provision at startup.","commonSituations":"A push block copied from a rewrite or header handler where the placeholder syntax or replacement regex is invalid; upgrading Caddy versions where header-op validation became stricter; HTTP/2 push being deprecated in browsers so configs linger untested for a long time.","solutions":["Read the '%v' tail of the message to identify the failing header operation and fix it.","Validate the config with 'caddy validate --config <file>' before deploying.","If the headers block is not needed for pushes, remove it; if push itself is unneeded (browsers deprecated it), drop the handler and use 103 Early Hints instead."],"exampleFix":"# before (Caddyfile)\nroute {\n  push {\n    headers {\n      set Link {http.response.header.link}*\n    }\n  }\n}\n\n# after\nroute {\n  push {\n    headers {\n      set Link \"</style.css>; rel=preload; as=style\"\n    }\n  }\n}","handlingStrategy":"validation","validationCode":"// before calling Provision on the push handler\ncopyHeaders := make(headers.HeaderOps, len(h.Headers.Add))\nif err := json.Unmarshal(headerJSON, &h); err != nil {\n    return fmt.Errorf(\"decoding push handler config: %v\", err)\n}\n// Provision errors surface at caddy.Run; validate config first instead:\n// caddy validate --config Caddyfile","typeGuard":null,"tryCatchPattern":"if err := pushHandler.Provision(ctx); err != nil {\n    if strings.Contains(err.Error(), \"provisioning header operations\") {\n        // inspect the wrapped cause before deciding: it is always a header-op config fault\n        log.Printf(\"push header config invalid: %v\", errors.Unwrap(err))\n    }\n    return err\n}","preventionTips":["Validate push header blocks with 'caddy validate' before reload.","Prefer literal header values over placeholders in push configs.","Consider dropping HTTP/2 push (deprecated by browsers) in favor of 103 Early Hints."],"tags":["http2-push","headers","provisioning","configuration"],"backgroundTag":null,"analyzedSha":"50e54ee279aa1e504fe218ca49ab6ae16c100410","analyzedAt":"2026-08-15T09:20:21.641Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}