hcengineering/platform · error · Error

Please provide front url

Error message

Please provide front url

What it means

getFrontUrl resolves the frontend base URL from branding.front, falling back to the FrontURL metadata, and throws Error('Please provide front url') when neither is set. Links in emails (confirmations, invites) need this base URL to be constructed.

Source

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

  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,
  db: AccountDB,
  workspace: WorkspaceUuid,
  value: boolean
): Promise<void> {
  const workspaceInfo = await getWorkspaceById(db, workspace)
  if (workspaceInfo === null) {
    throw new PlatformError(new Status(Severity.ERROR, platform.status.WorkspaceNotFound, { workspaceUuid: workspace }))
  }

  await db.workspaceStatus.update(
    { workspaceUuid: workspace },

View on GitHub (pinned to 63e28dc964)

Solutions

1. Set the FrontURL metadata (env/config) for the account service and restart.
2. Ensure the branding record includes a non-empty front field, or pass null branding so the fallback applies.
3. Check that neither config layer overrides FrontURL to an empty string.
4. Add a deployment smoke test that resolves getFrontUrl after startup.

Example fix

// config
// before
# FrontURL not set
// after
FrontURL=https://app.example.com

if (!branding?.front && !process.env.FRONT_URL) {
  throw new Error('Either branding.front or FrontURL metadata must be set')
}

function hasFrontUrl(branding: Branding | null): boolean {
  return Boolean(branding?.front) || Boolean(getMetadata(accountPlugin.metadata.FrontURL))
}

try {
  const front = getFrontUrl(branding)
} catch (err) {
  if (err instanceof Error && err.message.includes('front url')) {
    // configure FrontURL or pass branding with a front field
  } else throw err
}

When it happens

Trigger: Calling getFrontUrl(branding) when branding is null or branding.front is undefined AND metadata accountPlugin.metadata.FrontURL is missing or empty.

Common situations: Self-hosted deployments without FrontURL configured; branding object passed without a front field; migrating instances where the front URL was dropped from config.

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

• Key-value API URL not specified
• Please provide email service url
• SMTP config is required for custom transporter
• 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/b14bf5025a845c31. Report an issue: GitHub.