{"record":{"id":"2b7de723e2a5c128","repo":"perwendel/spark","slug":"the-filtermappingurlpattern-must-start-with","errorCode":null,"errorMessage":"The ${filterMappingUrlPattern} must start with \"/\" and end with \"/*\". It's: ${result}","messagePattern":"The (.+?) must start with \"/\" and end with \"/\\*\"\\. It's: (.+?)","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"src/main/java/spark/servlet/FilterTools.java","lineNumber":67,"sourceCode":"\n        if (!path.startsWith(SLASH)) {\n            path = SLASH + path;\n        }\n\n        try {\n            path = URLDecoder.decode(path, \"UTF-8\");\n        } catch (UnsupportedEncodingException ex) {\n            // this can't really ever happen\n        }\n        return path;\n    }\n\n    static String getFilterPath(FilterConfig config) {\n        String result = config.getInitParameter(FILTER_MAPPING_PARAM);\n        if (result == null || result.equals(SLASH_WILDCARD)) {\n            return \"\";\n        } else if (!result.startsWith(SLASH) || !result.endsWith(SLASH_WILDCARD)) {\n            throw new RuntimeException(\n                    \"The \" + FILTER_MAPPING_PARAM + \" must start with \\\"/\\\" and end with \\\"/*\\\". It's: \"\n                            + result\n            ); // NOSONAR\n        }\n        return result.substring(1, result.length() - 1);\n    }\n\n}\n","sourceCodeStart":49,"sourceCodeEnd":76,"githubUrl":"https://github.com/perwendel/spark/blob/1973e402f5d4c1442ad34a1d38ed0758079f7773/src/main/java/spark/servlet/FilterTools.java#L49-L76","documentation":"When Spark runs as a servlet filter, FilterTools.getFilterPath reads the filterMappingUrlPattern init parameter to determine the filter's path mapping. The value must be either \"/*\" (mapped to empty path) or a string starting with \"/\" and ending with \"/*\". Any other value is a configuration error, so Spark throws RuntimeException at filter initialization.","triggerScenarios":"Configuring the SparkFilter in web.xml (or programmatically) with a FilterConfig init parameter filterMappingUrlPattern that does not start with \"/\" or does not end with \"/*\" — e.g. \"api/*\", \"/api\", \"*\", or \"/api/**\".","commonSituations":"Hand-editing web.xml and writing \"/api\" instead of \"/api/*\"; copying servlet mapping syntax into the filter mapping parameter; typos such as missing leading slash after refactoring the app's base path.","solutions":["Set the filterMappingUrlPattern init parameter to a valid value like \"/*\" or \"/api/*\".","Ensure the value starts with a single \"/\" and ends with \"/*\".","If the filter should serve the whole app, either omit the init parameter or set it to \"/*\"."],"exampleFix":"<!-- before -->\n<init-param>\n  <param-name>filterMappingUrlPattern</param-name>\n  <param-value>/api</param-value>\n</init-param>\n\n<!-- after -->\n<init-param>\n  <param-name>filterMappingUrlPattern</param-name>\n  <param-value>/api/*</param-value>\n</init-param>","handlingStrategy":"validation","validationCode":"String pattern = config.getInitParameter(\"filterMappingUrlPattern\");\nif (pattern != null && !pattern.equals(\"/*\") &&\n    !(pattern.startsWith(\"/\") && pattern.endsWith(\"/*\"))) {\n    throw new IllegalStateException(\"filterMappingUrlPattern must be like /api/*\");\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Use exactly \"/*\" or \"/prefix/*\" in web.xml; never bare \"/prefix\" or \"*\".","Validate filter init-params in an integration test that boots the filter."],"tags":["servlet","configuration","web-xml","spark"],"backgroundTag":"invalid-config-value","analyzedSha":"1973e402f5d4c1442ad34a1d38ed0758079f7773","analyzedAt":"2026-09-10T14:38:22.866Z","contentChangedAt":"2026-09-10T14:38:22.866Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}