bytedance/deer-flow · warning · HTTPException

once schedule must be at least {config.scheduler.min_once_de

Error message

once schedule must be at least {config.scheduler.min_once_delay_seconds} seconds in the future

What it means

Raised as HTTP 422 by POST /api/scheduled-tasks when a once schedule's next_run_at is fewer than config.scheduler.min_once_delay_seconds in the future. The scheduler requires a minimum lead time to register and dispatch one-shot tasks reliably.

Source

Thrown at backend/app/gateway/routers/scheduled_tasks.py:107

        validate_timezone(body.timezone)
        if body.schedule_type == "cron":
            raw_cron = schedule_spec.get("cron")
            if not isinstance(raw_cron, str):
                raise HTTPException(status_code=422, detail="cron schedule requires schedule_spec.cron")
            schedule_spec["cron"] = normalize_cron_expression(raw_cron)
        next_run_at = compute_next_run_at(
            body.schedule_type,
            schedule_spec,
            body.timezone,
            now=datetime.now(UTC),
        )
    except ValueError as exc:
        raise HTTPException(status_code=422, detail=str(exc)) from exc

    if body.schedule_type == "once" and next_run_at is None:
        raise HTTPException(status_code=422, detail="once schedule must be in the future")
    if body.schedule_type == "once" and next_run_at is not None and (next_run_at - datetime.now(UTC)).total_seconds() < config.scheduler.min_once_delay_seconds:
        raise HTTPException(
            status_code=422,
            detail=(f"once schedule must be at least {config.scheduler.min_once_delay_seconds} seconds in the future"),
        )

    return await repo.create(
        task_id=f"task-{uuid.uuid4().hex}",
        user_id=str(user.id),
        thread_id=body.thread_id,
        context_mode=body.context_mode,
        assistant_id="lead_agent",
        title=body.title,
        prompt=body.prompt,
        schedule_type=body.schedule_type,
        schedule_spec=schedule_spec,
        timezone=body.timezone,
        next_run_at=next_run_at,
    )

View on GitHub (pinned to 1dd6ba1acb)

Solutions

1. Schedule the run at least min_once_delay_seconds ahead — the error message names the exact required number; use that + a safety margin.
2. If immediate execution is the goal, run the prompt directly via the chat/run API instead of a once task.
3. Operators can lower scheduler.min_once_delay_seconds in config.yaml if the default is too conservative, then restart the Gateway.

Example fix

// before
const runAt = new Date(Date.now() + 5_000).toISOString(); // may be < min delay
// after: use the minimum the backend enforces + margin
const runAt = new Date(Date.now() + (MIN_ONCE_DELAY_SECONDS + 30) * 1000).toISOString();

MIN_DELAY = get_scheduler_min_once_delay()  # from config/GW docs; match config.scheduler.min_once_delay_seconds
from datetime import datetime, UTC, timedelta
run_at = datetime.fromisoformat(body["schedule_spec"]["run_at"].replace("Z", "+00:00"))
assert run_at - datetime.now(UTC) >= timedelta(seconds=MIN_DELAY + 5), f"need >= {MIN_DELAY}s lead time"

const isBeyondMinDelay = (iso: string, minDelaySec: number): boolean =>
  (Date.parse(iso) - Date.now()) / 1000 > minDelaySec;

resp = requests.post(url, json=body, headers=auth)
if resp.status_code == 422 and "at least" in resp.json().get("detail", ""):
    body["schedule_spec"]["run_at"] = iso_now_plus(MIN_DELAY + 30)  # parse required delay from detail
    resp = requests.post(url, json=body, headers=auth)

When it happens

Trigger: A once run_at only seconds ahead while min_once_delay_seconds (config.yaml -> scheduler) is larger (commonly tens of seconds or more).

Common situations: Users scheduling 'in 5 seconds'; operator raised the minimum delay; tests using near-immediate timestamps.

Related errors

• once schedule must be in the future
• Unsupported context_mode
• reuse_thread requires thread_id
• Unsupported schedule_type
• cron schedule requires schedule_spec.cron

AI-assisted analysis of bytedance/deer-flow@1dd6ba1acb (2026-08-14). Data as JSON: /api/errors/7f7d85bc6897b2ec. Report an issue: GitHub.