{"record":{"id":"30d8f5fa40b37df9","repo":"spring-projects/spring-security","slug":"headers-security-is-enabled-but-no-headers-will-b","errorCode":null,"errorMessage":"Headers security is enabled, but no headers will be added. Either add headers or disable headers security","messagePattern":"Headers security is enabled, but no headers will be added\\. Either add headers or disable headers security","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"config/src/main/java/org/springframework/security/config/annotation/web/configurers/HeadersConfigurer.java","lineNumber":285,"sourceCode":"\t\tthis.hsts.disable();\n\t\tthis.frameOptions.disable();\n\t\treturn this;\n\t}\n\n\t@Override\n\tpublic void configure(H http) {\n\t\tHeaderWriterFilter headersFilter = createHeaderWriterFilter();\n\t\thttp.addFilter(headersFilter);\n\t}\n\n\t/**\n\t * Creates the {@link HeaderWriter}.\n\t * @return the {@link HeaderWriter}\n\t */\n\tprivate HeaderWriterFilter createHeaderWriterFilter() {\n\t\tList<HeaderWriter> writers = getHeaderWriters();\n\t\tif (writers.isEmpty()) {\n\t\t\tthrow new IllegalStateException(\n\t\t\t\t\t\"Headers security is enabled, but no headers will be added. Either add headers or disable headers security\");\n\t\t}\n\t\tHeaderWriterFilter headersFilter = new HeaderWriterFilter(writers);\n\t\theadersFilter = postProcess(headersFilter);\n\t\treturn headersFilter;\n\t}\n\n\t/**\n\t * Gets the {@link HeaderWriter} instances and possibly initializes with the defaults.\n\t * @return\n\t */\n\tprivate List<HeaderWriter> getHeaderWriters() {\n\t\tList<HeaderWriter> writers = new ArrayList<>();\n\t\taddIfNotNull(writers, this.contentTypeOptions.writer);\n\t\taddIfNotNull(writers, this.xssProtection.writer);\n\t\taddIfNotNull(writers, this.cacheControl.writer);\n\t\taddIfNotNull(writers, this.hsts.writer);\n\t\taddIfNotNull(writers, this.frameOptions.writer);","sourceCodeStart":267,"sourceCodeEnd":303,"githubUrl":"https://github.com/spring-projects/spring-security/blob/96852e8860138a482cb13d1479573f24ff6443c6/config/src/main/java/org/springframework/security/config/annotation/web/configurers/HeadersConfigurer.java#L267-L303","documentation":"HeadersConfigurer (headers() in HttpSecurity) is enabled by default but only functions when at least one HeaderWriter is registered. If the developer explicitly disabled all default writers (defaultsDisabled(), then removing everything) without adding any header writers, createHeaderWriterFilter() finds an empty writer list and throws IllegalStateException — the filter would do nothing useful.","triggerScenarios":"Calling http.headers().defaultsDisabled() plus removeHeaderValueWriter / disabling each default writer with no addHeaderWriter, then starting the application context.","commonSituations":"Intending to disable headers entirely but using defaultsDisabled() on an enabled headers() section instead of .disable(); selectively turning off writers one by one and accidentally removing all of them.","solutions":["Add at least one header writer, e.g. http.headers().defaultsDisabled().xssProtection(...) or frameOptions(...)","If headers are not wanted at all, call http.headers().disable() instead of leaving headers enabled with no writers","Re-enable the defaults by removing defaultsDisabled() if the standard security headers were intended"],"exampleFix":"// before\nhttp.headers(h -> h.defaultsDisabled());\n// after\nhttp.headers(h -> h.defaultsDisabled().frameOptions(fo -> fo.sameOrigin()));\n// or fully disable:\nhttp.headers(h -> h.disable());","handlingStrategy":"validation","validationCode":"// before finalizing headers config\nList<HeaderWriter> writers = getHeaderWriters(); // or inspect your headers lambda\nif (writers.isEmpty()) {\n    throw new IllegalStateException(\"headers enabled with no writers: add one or call headers().disable()\");\n}","typeGuard":"boolean hasHeaderWriters(HeadersConfigurer<HttpSecurity> h) {\n    return !h.getHeaderWriters().isEmpty();\n}","tryCatchPattern":"try {\n    http.headers(h -> h.defaultsDisabled().frameOptions(FrameOptionsConfig::sameOrigin));\n} catch (IllegalStateException e) {\n    if (e.getMessage().contains(\"no headers will be added\")) {\n        // either add a writer or use h.disable()\n    }\n}","preventionTips":["After defaultsDisabled(), always add at least one writer","Use .disable() rather than an empty headers() block when no headers are wanted","Don't remove default writers one-by-one without adding replacements"],"tags":["spring-security","headers","configuration","illegal-state"],"backgroundTag":"empty-required-field","analyzedSha":"96852e8860138a482cb13d1479573f24ff6443c6","analyzedAt":"2026-09-10T23:25:23.477Z","contentChangedAt":"2026-09-10T23:25:23.477Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}