knadh/listmonk · error

error compiling subject: %v

Error message

error compiling subject: %v

What it means

This error is raised by TxMessage.Render in models/messages.go when the message's Subject contains template expressions ({{ ... }}) that fail to parse as a Go text/template. Since the subject is explicitly set on the TxMessage and hasTplExpr detects template strings, Render compiles it with txttpl.New(BaseTpl).Funcs(funcs).Parse before execution; any parse failure is wrapped as "error compiling subject: %v". It is a template syntax/compile failure, not a data-rendering failure.

Source

Thrown at models/messages.go:115

		}
		if err := t.ExecuteTemplate(&b, BaseTpl, data); err != nil {
			return err
		}
		m.AltBody = b.String()
		b.Reset()
	}

	// Was a subject provided in the message?
	var (
		subjTpl *txttpl.Template
		subject = m.Subject
	)
	if subject != "" {
		if hasTplExpr(m.Subject) {
			// If the subject has a template string, render that.
			s, err := txttpl.New(BaseTpl).Funcs(funcs).Parse(m.Subject)
			if err != nil {
				return fmt.Errorf("error compiling subject: %v", err)
			}
			subjTpl = s
		}
	} else {
		// Use the subject from the template.
		subject = tpl.Subject
		subjTpl = tpl.SubjectTpl
	}

	// If the subject is also a template, render that.
	if subjTpl != nil {
		if err := subjTpl.ExecuteTemplate(&b, BaseTpl, data); err != nil {
			return err
		}
		m.Subject = b.String()
		b.Reset()
	} else {
		m.Subject = subject

View on GitHub (pinned to 670c01717d)

Solutions

1. Fix the template syntax in TxMessage.Subject per the wrapped error (unbalanced braces, bad function name, missing end tag).
2. Ensure all functions referenced in the subject exist in the FuncMap passed to Render.
3. If the subject needs no templating, remove all {{ }} expressions — it will then be used literally without compilation.
4. Test the subject string with text/template.Parse standalone to reproduce the exact parse error.
5. Review recent edits to the subject line via the admin UI/API for accidental brace corruption.

Example fix

// before
m.Subject = "Order {{ .Tx.ID } confirmation"
// after
m.Subject = "Order {{ .Tx.ID }} confirmation"

import ("strings" "text/template")

func validateSubject(subject string, funcs template.FuncMap) error {
	if subject == "" || !strings.Contains(subject, "{{") {
		return nil // literal subject; Render won't compile it
	}
	_, err := template.New("subject").Funcs(funcs).Parse(subject)
	return err
}

func hasTemplateExpr(s string) bool {
	return strings.Contains(s, "{{") && strings.Contains(s, "}}")
}

if err := msg.Render(sub, tpl, funcs); err != nil {
	if strings.HasPrefix(err.Error(), "error compiling subject") {
		log.Errorf("subject template syntax invalid: %v", err)
		msg.Subject = fallbackStaticSubject // or surface the error to the API caller
		return err
	}
	return err
}

When it happens

Trigger: Calling SendTxMessage (or previewTemplate) with TxMessage.Subject non-empty and containing invalid template syntax — e.g. "Receipt for {{ .Subscriber.Name " (unclosed action), "{{ .Tx.Amount | currencyee }}" (unknown function in the FuncMap), or unbalanced braces like "Order {{{ .Tx.ID }}".

Common situations: Typo'd function names in subject lines, pasting HTML-template syntax into a text/template subject, hand-edited subject lines via API that break brace pairing, missing custom template funcs after a version change of the mailing library.

Related errors

• error compiling alt body: %v
• error compiling subject: %v
• error compiling transactional template: %v
• 'email' column not found
• token was not found or has expired

AI-assisted analysis of knadh/listmonk@670c01717d (2026-09-01). Data as JSON: /api/errors/65dd304e9f86382d. Report an issue: GitHub.