xai-org/x-algorithm · error · IllegalArgumentException

Adhoc runs require a window: pass --date START END or --mont

Error message

Adhoc runs require a window: pass --date START END or --month YYYY-MM (production windows come from statebird via the *Prod scheduled app).

What it means

UnderTheHoodDates.getDateRange requires an adhoc time window: either --date START END or --month YYYY-MM must be present. Production runs get their window injected by the statebird-scheduled *Prod app; when neither arg is present the job refuses to run with an unbounded window.

Source

Thrown at under-the-hood/scalding/UnderTheHoodDates.scala:22

import com.twitter.scalding.DateParser
import com.twitter.scalding.DateRange
import com.twitter.scalding.RichDate
import java.util.Calendar
import java.util.TimeZone

object UnderTheHoodDates {

  def resolve(args: Args): DateRange = {
    implicit val tz: TimeZone = TimeZone.getTimeZone("UTC")
    implicit val dp: DateParser = DateParser.default
    val dates = args.list("date")
    if (dates.nonEmpty) DateRange.parse(dates)
    else
      args
        .optional("month")
        .map(monthRange)
        .getOrElse(
          throw new IllegalArgumentException(
            "Adhoc runs require a window: pass --date START END or --month YYYY-MM " +
              "(production windows come from statebird via the *Prod scheduled app)."))
  }

  def monthRange(ym: String): DateRange = {
    require(ym.matches("""\d{4}-\d{2}"""), s"--month must be YYYY-MM; got '$ym'")
    val Array(year, month) = ym.split("-").map(_.toInt)
    require(month >= 1 && month <= 12, s"--month has an invalid month: '$ym'")
    val cal = utcCal()
    cal.setLenient(false)
    cal.clear()
    cal.set(year, month - 1, 1, 0, 0, 0)
    val start = cal.getTimeInMillis
    cal.add(Calendar.MONTH, 1)
    DateRange(RichDate(start), RichDate(cal.getTimeInMillis - 1L))
  }

  private def utcCal(): Calendar = Calendar.getInstance(TimeZone.getTimeZone("UTC"))

View on GitHub (pinned to 24c60942c5)

Solutions

Add --date "2024-01-01 2024-01-02" (START END) or --month 2024-01 to the job args
Verify flag spelling exactly matches 'date' and 'month'
For production behavior, launch via the statebird-scheduled *Prod app instead of adhoc

Example fix

# before
hadoop jar uth.jar com.twitter.uth.Job --output /tmp/out
# after
hadoop jar uth.jar com.twitter.uth.Job --date 2024-01-01 2024-01-15 --output /tmp/out

Defensive patterns

Strategy: validation

Validate before calling

require(args.optional("date").isDefined || args.optional("month").isDefined, "pass --date or --month")

Try / catch

try getDateRange(args) catch { case e: IllegalArgumentException if e.getMessage.startsWith("Adhoc") => defaultLastWeek() }

Prevention

Add a wrapper script that refuses to launch without a window
Template adhoc commands with a placeholder date that must be filled
Document flag names in the job README

When it happens

Trigger: Running an adhoc scalding job with neither --date nor --month; running the non-Prod app locally where statebird does not inject a window; misspelling the flag names so both optionals are empty.

Common situations: Local development or one-off backfills where the operator forgot the window; copying a prod launch command but removing the scheduling wrapper; typo'd flags (--dates, --months).

Understand the failure class

Background: Missing required parameter errors: what 'X is required' and 'the required X param is missing' mean, and how to fix them — this error's family across 27 libraries.

Related errors

AI-assisted analysis of xai-org/x-algorithm@24c60942c5 (2026-08-28). Data as JSON: /api/errors/799dd0e11e5e0775. Report an issue: GitHub.