karatelabs/karate · error · TemplateProcessingException

karate-markup does not support param lists in th:fragment…

Error message

karate-markup does not support param lists in th:fragment signatures.\n  Change   th:fragment="name(p1, p2)"   ➜   th:fragment="name"\n  Pass values via th:with at the call site; ...\n  Original Thymeleaf error: ${thymeleafMsg}

What it means

karate-markup (KaThymeleaf) does not support parameter lists in th:fragment signatures, unlike stock Thymeleaf. When a fragment is declared with parameters, the library rewrites the raw Thymeleaf 'Cannot resolve fragment. Signature ...' error into this actionable message explaining the required change: declare the fragment without a parameter list and pass values via th:with at the call site.

Solutions

  1. Change the declaration to th:fragment="name" (no parentheses)
  2. Pass values at the call site with th:with="p1=..., p2=..." instead of fragment arguments
  3. Update all call sites (th:replace/th:insert) that used the parameterized form
  4. Test template rendering to confirm the fragment resolves

Example fix

<!-- before -->
<div th:fragment="card(title, body)">...</div>
<div th:replace="~{frag :: card('Hi', 'Text')}"></div>
<!-- after -->
<div th:fragment="card">...</div>
<div th:replace="~{frag :: card}" th:with="title='Hi', body='Text'"></div>
Defensive patterns

Strategy: validation

Validate before calling

Pattern SIG = Pattern.compile("th:fragment=\"([^\"]*)\\(([^\"]*)\\)\""); // scan templates; non-empty group(2) means param list -> fix before rendering

Try / catch

try { render(template, model); } catch (TemplateProcessingException e) { if (e.getMessage() != null && e.getMessage().contains("th:fragment")) { /* refactor fragment signature per message */ } throw e; }

Prevention

When it happens

Trigger: Rendering a template containing th:fragment="name(p1, p2)" (a parameterized fragment signature), either detected proactively by KaFragmentProcessor or via a Thymeleaf TemplateProcessingException whose message contains 'Cannot resolve fragment. Signature'.

Common situations: Migrating existing Thymeleaf templates into karate-markup; copy-pasting standard Thymeleaf fragment examples from documentation; converting a layout system that relied on fragment parameters.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

AI-assisted analysis of karatelabs/karate@a22eb90246 (2026-09-12). Data as JSON: /api/errors/bf20037540f8ccde. Report an issue: GitHub.

Appendix: source

Thrown at karate-core/src/main/java/io/karatelabs/markup/FragmentSupport.java:65

 * </ul>
 */
final class FragmentSupport {

    private FragmentSupport() {
    }

    /**
     * If the given Thymeleaf exception originated from strict-signature matching,
     * throw a {@link TemplateProcessingException} whose message points at the
     * karate-markup convention. Otherwise return without throwing — caller
     * propagates the original.
     */
    static void translateSignatureError(TemplateProcessingException e) {
        String msg = e.getMessage();
        if (msg == null || !msg.contains("Cannot resolve fragment. Signature")) {
            return;
        }
        throw new TemplateProcessingException(signatureMessage(null, null, msg), e);
    }

    /**
     * Build the karate-flavoured "param lists not supported" message. Used by
     * both the proactive {@link KaFragmentProcessor} (which passes the offending
     * attribute value) and {@link #translateSignatureError} (which only has the
     * Thymeleaf message). Either argument may be {@code null}.
     */
    static String signatureMessage(String offendingValue, String resourceDescription, String thymeleafMsg) {
        StringBuilder sb = new StringBuilder();
        sb.append("karate-markup does not support param lists in th:fragment signatures.\n");
        if (offendingValue != null) {
            sb.append("  Found    th:fragment=\"").append(offendingValue).append("\"");
            if (resourceDescription != null) {
                sb.append("   in ").append(resourceDescription);
            }
            sb.append("\n");
        }

View on GitHub (pinned to a22eb90246)