cloudreve/cloudreve · error

failed to execute email template: %w

Error message

failed to execute email template: %w

What it means

The reset-email body parsed but executing it against ResetContext failed. Execution errors come from unknown fields/methods on the context, nil dereferences, or functions returning errors while rendering the (usually HTML) body.

Source

Thrown at pkg/email/template.go:60

	if err != nil {
		return "", "", fmt.Errorf("failed to parse email title: %w", err)
	}

	var resTitle strings.Builder
	err = tmplTitle.Execute(&resTitle, resetCtx)
	if err != nil {
		return "", "", fmt.Errorf("failed to execute email title: %w", err)
	}

	tmplBody, err := template.New("resetBody").Parse(selected.Body)
	if err != nil {
		return "", "", fmt.Errorf("failed to parse email template: %w", err)
	}

	var resBody strings.Builder
	err = tmplBody.Execute(&resBody, resetCtx)
	if err != nil {
		return "", "", fmt.Errorf("failed to execute email template: %w", err)
	}

	return resTitle.String(), resBody.String(), nil
}

// ActivationContext used for variables in activation email
type ActivationContext struct {
	*CommonContext
	User *ent.User
	Url  string
}

// NewActivationEmail generates activation email from template
func NewActivationEmail(ctx context.Context, settings setting.Provider, user *ent.User, url string) (string, string, error) {
	templates := settings.ActivationEmailTemplate(ctx)
	if len(templates) == 0 {
		return "", "", fmt.Errorf("activation email template not configured")
	}

View on GitHub (pinned to 20c95ad73f)

Solutions

1. Validate each variable in the body against ResetContext fields (SiteBasic, Logo, SiteUrl, User, Url) and the ent.User fields used
2. Fix or remove unknown fields; use {{if}} guards around optional ones
3. Test-render the body with a sample ResetContext in a unit test before saving to settings
4. After fixing, verify with a real password-reset request

Example fix

// before (body template)
<p>Welcome to {{.SiteTitle}}, {{.UserName}}</p>
// after
<p>Welcome to {{.SiteBasic.Title}}, {{.User.Name}}</p>

func bodyExecutes(body string, sample ResetContext) error {
    t, err := template.New("b").Parse(body)
    if err != nil {
        return err
    }
    return t.Execute(io.Discard, sample)
}

_, _, err := email.NewResetEmail(ctx, settings, user, url)
if err != nil && strings.Contains(err.Error(), "failed to execute email template") {
    // Execute errors name the offending field: log it verbatim for the admin
    log.Error("reset body template field error: %v", err)
}

When it happens

Trigger: Body references {{.SiteUrl.Title}} although SiteUrl is a plain string, {{.User.Name}} with a nil User, or any field not present on ResetContext/CommonContext; a range over a non-collection field.

Common situations: Rich HTML templates using variables documented for a different version or a different email type; templates assuming nested settings fields that were flattened.

Related errors

• failed to execute email title: %w
• reset email template not configured
• failed to parse email title: %w
• failed to parse email template: %w
• activation email template not configured

AI-assisted analysis of cloudreve/cloudreve@20c95ad73f (2026-08-16). Data as JSON: /api/errors/00c7188f32d52e44. Report an issue: GitHub.