What causes "'subject' is missing" in hcengineering/platform?

Always include a non-undefined subject string in the request body.

'subject' is missing

Error message

'subject' is missing

What it means

handleSendMail returns HTTP 400 { err: "'subject' is missing" } when the subject field is absent from the request body. This validation runs after the text/html check and before the recipient check.

Source

Thrown at services/mail/pod-mail/src/main.ts:102

): Promise<void> {
  const { from, to, subject, text, html, attachments, headers, apiKey, password } = req.body
  if (process.env.API_KEY !== undefined && process.env.API_KEY !== apiKey) {
    ctx.warn('Unauthorized access attempt to send email', {
      from,
      to
    })
    res.status(401).send({ err: 'Unauthorized' })
    return
  }
  const fromAddress = from ?? config.source
  if (text === undefined && html === undefined) {
    ctx.warn('Text and html are missing in email request', { from, to })
    res.status(400).send({ err: "'text' and 'html' are missing" })
    return
  }
  if (subject === undefined) {
    ctx.warn('Subject is missing in email request', { from, to })
    res.status(400).send({ err: "'subject' is missing" })
    return
  }
  if (to === undefined) {
    ctx.warn('To address is missing in email request', { from })
    res.status(400).send({ err: "'to' is missing" })
    return
  }
  if (fromAddress === undefined) {
    ctx.warn('From address is missing in email request', { to })
    res.status(400).send({ err: "'from' is missing" })
    return
  }
  const message: SendMailOptions = {
    from: fromAddress,
    to,
    subject,
    text
  }

View on GitHub (pinned to 63e28dc964)

Solutions

Always include a non-undefined subject string in the request body.
If the subject is optional in your domain, pass an explicit empty string '' instead of undefined.
Fix client serializers that strip undefined/empty fields before send.

Example fix

// before
sendMail({ to, text, subject: maybeSubject }) // undefined subject -> 400
// after
sendMail({ to, text, subject: maybeSubject ?? '' })

Defensive patterns

Strategy: validation

Validate before calling

function assertSubject(m: { subject?: string }): void {
  if (m.subject === undefined) throw new Error("email requires a 'subject' field (use '' if intentionally empty)")
}

Type guard

function hasSubject(m: { subject?: unknown }): m is { subject: string } {
  return m.subject !== undefined
}

Try / catch

if (!hasSubject(mail)) mail.subject = ''
const res = await fetch(mailUrl, { method: 'POST', body: JSON.stringify(mail) })
if (res.status === 400) throw new Error(`mail rejected: ${(await res.json()).err}`)

Prevention

Treat subject as required even if your domain considers it optional; pass '' instead of undefined.
Remember JSON.stringify drops undefined properties.
Keep client mail wrappers aligned with pod-mail's required-field list (subject, to, text/html).
Add pre-send payload validation in shared mail utilities.

When it happens

Trigger: POST to the send-mail endpoint with text or html present but subject undefined — e.g. { to, text } only, subject explicitly set to undefined by a serializer that drops it, or a client wrapper that omits empty subjects.

Common situations: Automated notification builders that treat subject as optional; JSON.stringify dropping undefined subject values; migrating from a mail API where subject was optional to pod-mail where it is required.

Related errors

AI-assisted analysis of hcengineering/platform@63e28dc964 (2026-08-29). Data as JSON: /api/errors/4febf6ff88e6c609. Report an issue: GitHub.