hcengineering/platform · error · Error

Please provide email service url

Error message

Please provide email service url

What it means

getMailUrl reads the MAIL_URL metadata and throws a plain Error('Please provide email service url') when it is undefined or empty. It is the synchronous accessor variant used by mail-sending helpers, guaranteeing callers never proceed without a configured mail endpoint.

Source

Thrown at server/account/src/utils.ts:1437

    return invite
  }

  return await db.invite.findOne({ migratedFrom: id })
}

export async function getSocialIdByKey (db: AccountDB, socialKey: string): Promise<SocialId | null> {
  return await db.socialId.findOne({ key: socialKey })
}

export async function getEmailSocialId (db: AccountDB, email: string): Promise<SocialId | null> {
  return await db.socialId.findOne({ type: SocialIdType.EMAIL, value: email })
}

export function getMailUrl (): { mailURL: string, mailAuth: string | undefined } {
  const mailURL = getMetadata(accountPlugin.metadata.MAIL_URL)

  if (mailURL === undefined || mailURL === '') {
    throw new Error('Please provide email service url')
  }
  const mailAuth = getMetadata(accountPlugin.metadata.MAIL_AUTH_TOKEN)

  return { mailURL, mailAuth }
}

export function getFrontUrl (branding: Branding | null): string {
  const front = branding?.front ?? getMetadata(accountPlugin.metadata.FrontURL)

  if (front === undefined || front === '') {
    throw new Error('Please provide front url')
  }

  return front
}

export async function updateArchiveInfo (
  ctx: MeasureContext,

View on GitHub (pinned to 63e28dc964)

Solutions

1. Set MAIL_URL in the account service configuration and restart.
2. Validate deployment values (helm values/secret) contain MAIL_URL before rollout.
3. For local dev, point MAIL_URL at a local SMTP catcher or mock mailer.
4. Add a startup check that fails fast if MAIL_URL is absent.

Example fix

// env/config
// before
MAIL_URL=
// after
MAIL_URL=smtp://user:pass@smtp.example.com:587

if (!process.env.MAIL_URL) {
  throw new Error('MAIL_URL is required for mail sending')
}

try {
  const { mailURL, mailAuth } = getMailUrl()
  // send mail
} catch (err) {
  if (err instanceof Error && err.message.includes('email service url')) {
    // fail fast with a config-setup message pointing to MAIL_URL docs
  } else throw err
}

When it happens

Trigger: Any code path that calls getMailUrl() on an account server where metadata accountPlugin.metadata.MAIL_URL is missing or empty.

Common situations: Self-hosted instance without the mail service URL configured; env var dropped during redeployment or secret rotation; running only part of the platform locally where mail was never set up.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

• SMTP config is required for custom transporter
• Key-value API URL not specified
• Please provide front url
• Payment provider is not configured. Please provide payment p
• No screen access granted

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