perwendel/spark · error · RuntimeException

The must start with "/" and end with "/*". It's

Error message

The ${filterMappingUrlPattern} must start with "/" and end with "/*". It's: ${result}

What it means

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.

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 "/*".

Example fix

<!-- before -->
<init-param>
  <param-name>filterMappingUrlPattern</param-name>
  <param-value>/api</param-value>
</init-param>

<!-- after -->
<init-param>
  <param-name>filterMappingUrlPattern</param-name>
  <param-value>/api/*</param-value>
</init-param>

Defensive patterns

Strategy: validation

Validate before calling

String pattern = config.getInitParameter("filterMappingUrlPattern");
if (pattern != null && !pattern.equals("/*") &&
    !(pattern.startsWith("/") && pattern.endsWith("/*"))) {
    throw new IllegalStateException("filterMappingUrlPattern must be like /api/*");
}

Prevention

Use exactly "/*" or "/prefix/*" in web.xml; never bare "/prefix" or "*".
Validate filter init-params in an integration test that boots the filter.

When it happens

Trigger: 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/**".

Common situations: 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.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

AI-assisted analysis of perwendel/spark@1973e402f5 (2026-09-10). Data as JSON: /api/errors/2b7de723e2a5c128. Report an issue: GitHub.

Appendix: source

Thrown at src/main/java/spark/servlet/FilterTools.java:67

        if (!path.startsWith(SLASH)) {
            path = SLASH + path;
        }

        try {
            path = URLDecoder.decode(path, "UTF-8");
        } catch (UnsupportedEncodingException ex) {
            // this can't really ever happen
        }
        return path;
    }

    static String getFilterPath(FilterConfig config) {
        String result = config.getInitParameter(FILTER_MAPPING_PARAM);
        if (result == null || result.equals(SLASH_WILDCARD)) {
            return "";
        } else if (!result.startsWith(SLASH) || !result.endsWith(SLASH_WILDCARD)) {
            throw new RuntimeException(
                    "The " + FILTER_MAPPING_PARAM + " must start with \"/\" and end with \"/*\". It's: "
                            + result
            ); // NOSONAR
        }
        return result.substring(1, result.length() - 1);
    }

}

View on GitHub (pinned to 1973e402f5)