tessl/golang-github-com-go-co-op-gocron-v2

A Golang job scheduling library that lets you run Go functions at pre-determined intervals using cron expressions, fixed durations, daily, weekly, monthly, or one-time schedules with support for distributed deployments.

Overview

Eval results

Files

Error Reference

Name: tessl/golang-github-com-go-co-op-gocron-v2
Author: tessl

All gocron errors are defined as package-level var values and can be matched with errors.Is.

Import

import "github.com/go-co-op/gocron/v2"

Complete Error List

var (
    // Scheduler / executor errors
    ErrStopExecutorTimedOut   = errors.New("gocron: timed out waiting for executor to stop")
    ErrStopJobsTimedOut       = errors.New("gocron: timed out waiting for jobs to finish")
    ErrStopSchedulerTimedOut  = errors.New("gocron: timed out waiting for scheduler to stop")

    // Job not found / run errors
    ErrJobNotFound            = errors.New("gocron: job not found")
    ErrJobRunNowFailed        = errors.New("gocron: Job: RunNow: scheduler unreachable")

    // NewJob task validation errors
    ErrNewJobTaskNil                 = errors.New("gocron: NewJob: Task must not be nil")
    ErrNewJobTaskNotFunc             = errors.New("gocron: NewJob: Task.Function must be of kind reflect.Func")
    ErrNewJobWrongNumberOfParameters = errors.New("gocron: NewJob: Number of provided parameters does not match expected")
    ErrNewJobWrongTypeOfParameters   = errors.New("gocron: NewJob: Type of provided parameters does not match expected")

    // Panic recovery
    ErrPanicRecovered = errors.New("gocron: panic recovered")

    // CronJob errors
    ErrCronJobInvalid = errors.New("gocron: CronJob: invalid crontab")
    ErrCronJobParse   = errors.New("gocron: CronJob: crontab parse failure")

    // DurationJob errors
    ErrDurationJobIntervalZero     = errors.New("gocron: DurationJob: time interval is 0")
    ErrDurationJobIntervalNegative = errors.New("gocron: DurationJob: time interval must be greater than 0")

    // DurationRandomJob errors
    ErrDurationRandomJobPositive = errors.New("gocron: DurationRandomJob: minimum and maximum durations must be greater than 0")
    ErrDurationRandomJobMinMax   = errors.New("gocron: DurationRandomJob: minimum duration must be less than maximum duration")

    // DailyJob errors
    ErrDailyJobAtTimeNil      = errors.New("gocron: DailyJob: atTime within atTimes must not be nil")
    ErrDailyJobAtTimesNil     = errors.New("gocron: DailyJob: atTimes must not be nil")
    ErrDailyJobHours          = errors.New("gocron: DailyJob: atTimes hours must be between 0 and 23 inclusive")
    ErrDailyJobZeroInterval   = errors.New("gocron: DailyJob: interval must be greater than 0")
    ErrDailyJobMinutesSeconds = errors.New("gocron: DailyJob: atTimes minutes and seconds must be between 0 and 59 inclusive")

    // WeeklyJob errors
    ErrWeeklyJobAtTimeNil         = errors.New("gocron: WeeklyJob: atTime within atTimes must not be nil")
    ErrWeeklyJobAtTimesNil        = errors.New("gocron: WeeklyJob: atTimes must not be nil")
    ErrWeeklyJobDaysOfTheWeekNil  = errors.New("gocron: WeeklyJob: daysOfTheWeek must not be nil")
    ErrWeeklyJobHours             = errors.New("gocron: WeeklyJob: atTimes hours must be between 0 and 23 inclusive")
    ErrWeeklyJobZeroInterval      = errors.New("gocron: WeeklyJob: interval must be greater than 0")
    ErrWeeklyJobMinutesSeconds    = errors.New("gocron: WeeklyJob: atTimes minutes and seconds must be between 0 and 59 inclusive")

    // MonthlyJob errors
    ErrMonthlyJobDays          = errors.New("gocron: MonthlyJob: daysOfTheMonth must be between 31 and -31 inclusive, and not 0")
    ErrMonthlyJobAtTimeNil     = errors.New("gocron: MonthlyJob: atTime within atTimes must not be nil")
    ErrMonthlyJobAtTimesNil    = errors.New("gocron: MonthlyJob: atTimes must not be nil")
    ErrMonthlyJobDaysNil       = errors.New("gocron: MonthlyJob: daysOfTheMonth must not be nil")
    ErrMonthlyJobHours         = errors.New("gocron: MonthlyJob: atTimes hours must be between 0 and 23 inclusive")
    ErrMonthlyJobZeroInterval  = errors.New("gocron: MonthlyJob: interval must be greater than 0")
    ErrMonthlyJobMinutesSeconds = errors.New("gocron: MonthlyJob: atTimes minutes and seconds must be between 0 and 59 inclusive")

    // OneTimeJob errors
    ErrOneTimeJobStartDateTimePast = errors.New("gocron: OneTimeJob: start must not be in the past")

    // Event listener errors
    ErrEventListenerFuncNil = errors.New("gocron: eventListenerFunc must not be nil")

    // WithStartAt / WithStopAt errors
    ErrWithStartDateTimePast      = errors.New("gocron: WithStartDateTime: start must not be in the past")
    ErrWithStartDateTimePastZero  = errors.New("gocron: WithStartDateTime: start must not be zero")
    ErrWithStopDateTimePast       = errors.New("gocron: WithStopDateTime: end must not be in the past")
    ErrStartTimeLaterThanEndTime  = errors.New("gocron: WithStartDateTime: start must not be later than end")
    ErrStopTimeEarlierThanStartTime = errors.New("gocron: WithStopDateTime: end must not be earlier than start")

    // SchedulerOption validation errors
    ErrWithClockNil                  = errors.New("gocron: WithClock: clock must not be nil")
    ErrWithContextNil                = errors.New("gocron: WithContext: context must not be nil")
    ErrWithDistributedElectorNil     = errors.New("gocron: WithDistributedElector: elector must not be nil")
    ErrWithDistributedLockerNil      = errors.New("gocron: WithDistributedLocker: locker must not be nil")
    ErrWithDistributedJobLockerNil   = errors.New("gocron: WithDistributedJobLocker: locker must not be nil")
    ErrWithIdentifierNil             = errors.New("gocron: WithIdentifier: identifier must not be nil")
    ErrWithLimitConcurrentJobsZero   = errors.New("gocron: WithLimitConcurrentJobs: limit must be greater than 0")
    ErrWithLimitedRunsZero           = errors.New("gocron: WithLimitedRuns: limit must be greater than 0")
    ErrWithLocationNil               = errors.New("gocron: WithLocation: location must not be nil")
    ErrWithLoggerNil                 = errors.New("gocron: WithLogger: logger must not be nil")
    ErrWithMonitorNil                = errors.New("gocron: WithMonitor: monitor must not be nil")
    ErrWithNameEmpty                 = errors.New("gocron: WithName: name must not be empty")
    ErrWithSchedulerMonitorNil       = errors.New("gocron: WithSchedulerMonitor: scheduler monitor cannot be nil")
    ErrSchedulerMonitorNil           = errors.New("gocron: WithSchedulerMonitor: monitor must not be nil")
    ErrWithStopTimeoutZeroOrNegative = errors.New("gocron: WithStopTimeout: timeout must be greater than 0")
)

Error Handling Pattern

j, err := s.NewJob(
    gocron.CronJob("invalid", false),
    gocron.NewTask(myFunc),
)
if err != nil {
    if errors.Is(err, gocron.ErrCronJobParse) {
        log.Fatal("invalid cron expression")
    }
    log.Fatal("failed to create job:", err)
}

Errors by Category

Scheduler Lifecycle Errors

ErrStopExecutorTimedOut

Returned by: Shutdown(), StopJobs()
When: The executor did not stop within the timeout (set via WithStopTimeout)
Action: Increase timeout or investigate long-running jobs

ErrStopJobsTimedOut

Returned by: StopJobs()
When: Some jobs did not complete within the timeout
Action: Increase timeout, check job cancellation logic, or use shorter timeouts for individual jobs

ErrStopSchedulerTimedOut

Returned by: Shutdown(), StopJobs()
When: Scheduler did not stop within the timeout
Action: Increase timeout or debug scheduler hang

Job Management Errors

ErrJobNotFound

Returned by: RemoveJob(), Job.LastRun(), Job.NextRun(), Job.NextRuns()
When: The job has been removed or never existed
Action: Check that the job hasn't been removed elsewhere

ErrJobRunNowFailed

Returned by: Job.RunNow()
When: The scheduler is unreachable (e.g., not started or shut down)
Action: Ensure scheduler is running before calling RunNow()

Task Validation Errors

ErrNewJobTaskNil

Returned by: NewJob(), Update()
When: Task argument is nil
Action: Provide a valid Task created with NewTask()

ErrNewJobTaskNotFunc

Returned by: NewJob(), Update()
When: Task.Function is not a function (e.g., a struct, int, etc.)
Action: Ensure you pass a function to NewTask()

ErrNewJobWrongNumberOfParameters

Returned by: NewJob(), Update()
When: Number of parameters passed to NewTask() doesn't match function signature
Action: Match parameter count to function signature (excluding auto-injected context)

ErrNewJobWrongTypeOfParameters

Returned by: NewJob(), Update()
When: Parameter types passed to NewTask() don't match function signature
Action: Ensure parameter types match exactly

Panic Recovery

ErrPanicRecovered

Available via: AfterJobRunsWithPanic event listener
When: A job panics during execution
Action: Fix the panic in the job function; gocron recovers and reschedules the job

CronJob Errors

ErrCronJobInvalid

Returned by: NewJob() with CronJob()
When: Cron expression is syntactically invalid
Action: Fix cron expression syntax

ErrCronJobParse

Returned by: NewJob() with CronJob()
When: Cron expression cannot be parsed
Action: Check cron expression format (5 or 6 fields, withSeconds flag)

Example valid expressions:

5-field (minute hour day month weekday): "0 9 * * *" (9 AM daily)
6-field (second minute hour day month weekday): "30 0 9 * * *" (9:00:30 AM daily, withSeconds=true)
Timezone prefix: "TZ=America/Chicago 0 9 * * *"

DurationJob Errors

ErrDurationJobIntervalZero

Returned by: NewJob() with DurationJob(0)
When: Interval is exactly 0
Action: Use a positive duration

ErrDurationJobIntervalNegative

Returned by: NewJob() with DurationJob(negative)
When: Interval is negative
Action: Use a positive duration

DurationRandomJob Errors

ErrDurationRandomJobPositive

Returned by: NewJob() with DurationRandomJob()
When: Either minimum or maximum duration is ≤ 0
Action: Both durations must be positive

ErrDurationRandomJobMinMax

Returned by: NewJob() with DurationRandomJob()
When: Minimum duration is ≥ maximum duration
Action: Ensure minDuration < maxDuration

DailyJob Errors

ErrDailyJobZeroInterval

Returned by: NewJob() with DailyJob(0, ...)
When: Interval is 0
Action: Use interval ≥ 1

ErrDailyJobAtTimesNil

Returned by: NewJob() with DailyJob(..., nil)
When: atTimes is nil
Action: Provide at least one time via NewAtTimes()

ErrDailyJobAtTimeNil

Returned by: NewJob() with DailyJob()
When: One of the atTime values in atTimes is nil
Action: Ensure all times are created with NewAtTime()

ErrDailyJobHours

Returned by: NewJob() with DailyJob()
When: Hours are not in range 0-23
Action: Use hours 0-23 inclusive

ErrDailyJobMinutesSeconds

Returned by: NewJob() with DailyJob()
When: Minutes or seconds are not in range 0-59
Action: Use minutes/seconds 0-59 inclusive

WeeklyJob Errors

ErrWeeklyJobZeroInterval

Returned by: NewJob() with WeeklyJob(0, ...)
When: Interval is 0
Action: Use interval ≥ 1

ErrWeeklyJobDaysOfTheWeekNil

Returned by: NewJob() with WeeklyJob(..., nil, ...)
When: daysOfTheWeek is nil
Action: Provide at least one weekday via NewWeekdays()

ErrWeeklyJobAtTimesNil

Returned by: NewJob() with WeeklyJob(..., ..., nil)
When: atTimes is nil
Action: Provide at least one time via NewAtTimes()

ErrWeeklyJobAtTimeNil

Returned by: NewJob() with WeeklyJob()
When: One of the atTime values in atTimes is nil
Action: Ensure all times are created with NewAtTime()

ErrWeeklyJobHours

Returned by: NewJob() with WeeklyJob()
When: Hours are not in range 0-23
Action: Use hours 0-23 inclusive

ErrWeeklyJobMinutesSeconds

Returned by: NewJob() with WeeklyJob()
When: Minutes or seconds are not in range 0-59
Action: Use minutes/seconds 0-59 inclusive

MonthlyJob Errors

ErrMonthlyJobZeroInterval

Returned by: NewJob() with MonthlyJob(0, ...)
When: Interval is 0
Action: Use interval ≥ 1

ErrMonthlyJobDaysNil

Returned by: NewJob() with MonthlyJob(..., nil, ...)
When: daysOfTheMonth is nil
Action: Provide at least one day via NewDaysOfTheMonth()

ErrMonthlyJobDays

Returned by: NewJob() with MonthlyJob()
When: Day is not in range 1-31 or -1 to -31 (excluding 0)
Action: Use days 1-31 (from start) or -1 to -31 (from end)

ErrMonthlyJobAtTimesNil

Returned by: NewJob() with MonthlyJob(..., ..., nil)
When: atTimes is nil
Action: Provide at least one time via NewAtTimes()

ErrMonthlyJobAtTimeNil

Returned by: NewJob() with MonthlyJob()
When: One of the atTime values in atTimes is nil
Action: Ensure all times are created with NewAtTime()

ErrMonthlyJobHours

Returned by: NewJob() with MonthlyJob()
When: Hours are not in range 0-23
Action: Use hours 0-23 inclusive

ErrMonthlyJobMinutesSeconds

Returned by: NewJob() with MonthlyJob()
When: Minutes or seconds are not in range 0-59
Action: Use minutes/seconds 0-59 inclusive

OneTimeJob Errors

ErrOneTimeJobStartDateTimePast

Returned by: NewJob() with OneTimeJob()
When: All specified start times are in the past (relative to scheduler clock)
Action: Provide at least one future time, or use OneTimeJobStartImmediately()

Event Listener Errors

ErrEventListenerFuncNil

Returned by: WithEventListeners() during NewJob()
When: An event listener function is nil
Action: Provide a non-nil function for each listener

Job Lifecycle Errors

ErrWithStartDateTimePast

Returned by: WithStartAt(WithStartDateTime(...))
When: Start time is in the past (relative to scheduler clock)
Action: Provide a future time, or use WithStartDateTimePast() to allow backdating

ErrWithStartDateTimePastZero

Returned by: WithStartAt(WithStartDateTimePast(...))
When: Start time is zero (time.Time{})
Action: Provide a valid non-zero time

ErrWithStopDateTimePast

Returned by: WithStopAt(WithStopDateTime(...))
When: Stop time is in the past (relative to scheduler clock)
Action: Provide a future time

ErrStartTimeLaterThanEndTime

Returned by: NewJob() when both WithStartAt and WithStopAt are set
When: Start time is after stop time
Action: Ensure start time < stop time

ErrStopTimeEarlierThanStartTime

Returned by: NewJob() when both WithStartAt and WithStopAt are set
When: Stop time is before start time
Action: Ensure start time < stop time

Scheduler Option Errors

ErrWithClockNil

Returned by: NewScheduler(WithClock(nil))
When: Clock is nil
Action: Provide a valid clockwork.Clock (typically for testing)

ErrWithContextNil

Returned by: WithContext(nil)
When: Context is nil
Action: Provide a non-nil context

ErrWithDistributedElectorNil

Returned by: NewScheduler(WithDistributedElector(nil))
When: Elector is nil
Action: Provide a valid Elector implementation

ErrWithDistributedLockerNil

Returned by: NewScheduler(WithDistributedLocker(nil))
When: Locker is nil
Action: Provide a valid Locker implementation

ErrWithDistributedJobLockerNil

Returned by: WithDistributedJobLocker(nil)
When: Per-job locker is nil
Action: Provide a valid Locker implementation

ErrWithIdentifierNil

Returned by: WithIdentifier(uuid.Nil)
When: UUID is nil
Action: Provide a non-nil UUID

ErrWithLimitConcurrentJobsZero

Returned by: NewScheduler(WithLimitConcurrentJobs(0, ...))
When: Limit is 0
Action: Use limit ≥ 1

ErrWithLimitedRunsZero

Returned by: WithLimitedRuns(0)
When: Limit is 0
Action: Use limit ≥ 1

ErrWithLocationNil

Returned by: NewScheduler(WithLocation(nil))
When: Location is nil
Action: Provide a valid *time.Location

ErrWithLoggerNil

Returned by: NewScheduler(WithLogger(nil))
When: Logger is nil
Action: Provide a valid Logger implementation

ErrWithMonitorNil

Returned by: NewScheduler(WithMonitor(nil)) or NewScheduler(WithMonitorStatus(nil))
When: Monitor is nil
Action: Provide a valid Monitor or MonitorStatus implementation

ErrWithNameEmpty

Returned by: WithName("")
When: Name is empty string
Action: Provide a non-empty name

ErrSchedulerMonitorNil / ErrWithSchedulerMonitorNil

Returned by: NewScheduler(WithSchedulerMonitor(nil))
When: Scheduler monitor is nil
Action: Provide a valid SchedulerMonitor implementation

ErrWithStopTimeoutZeroOrNegative

Returned by: NewScheduler(WithStopTimeout(0)) or NewScheduler(WithStopTimeout(-1))
When: Timeout is ≤ 0
Action: Use a positive timeout duration

Which Functions Return Which Errors

Error	Returned by
`ErrCronJobInvalid`	`NewJob` with `CronJob`
`ErrCronJobParse`	`NewJob` with `CronJob`
`ErrDailyJob*`	`NewJob` with `DailyJob`
`ErrDurationJobInterval*`	`NewJob` with `DurationJob`
`ErrDurationRandomJob*`	`NewJob` with `DurationRandomJob`
`ErrEventListenerFuncNil`	`WithEventListeners` (during `NewJob`)
`ErrJobNotFound`	`RemoveJob`, `Job.LastRun`, `Job.NextRun`, `Job.NextRuns`
`ErrJobRunNowFailed`	`Job.RunNow`
`ErrMonthlyJob*`	`NewJob` with `MonthlyJob`
`ErrNewJobTask*`	`NewJob` (task validation)
`ErrNewJobWrong*`	`NewJob` (parameter validation)
`ErrOneTimeJobStartDateTimePast`	`NewJob` with `OneTimeJob`
`ErrPanicRecovered`	Internal executor (available via `AfterJobRunsWithPanic`)
`ErrStartTimeLaterThanEndTime`	`WithStartAt(WithStartDateTime(...))`
`ErrStopExecutorTimedOut`	`Shutdown`, `StopJobs`
`ErrStopJobsTimedOut`	`StopJobs`
`ErrStopSchedulerTimedOut`	`Shutdown`, `StopJobs`
`ErrStopTimeEarlierThanStartTime`	`WithStopAt(WithStopDateTime(...))`
`ErrWeeklyJob*`	`NewJob` with `WeeklyJob`
`ErrSchedulerMonitorNil`	`WithSchedulerMonitor`
`ErrWith*`	Corresponding `SchedulerOption` or `JobOption`

Common Error Scenarios

Invalid Cron Expression

j, err := s.NewJob(
    gocron.CronJob("invalid cron", false),
    gocron.NewTask(myFunc),
)
if errors.Is(err, gocron.ErrCronJobParse) {
    log.Printf("Invalid cron expression: %v", err)
}

Job Not Found After Removal

j, _ := s.NewJob(gocron.DurationJob(time.Minute), gocron.NewTask(myFunc))
s.RemoveJob(j.ID())

// Later
nextRun, err := j.NextRun()
if errors.Is(err, gocron.ErrJobNotFound) {
    log.Println("Job was removed")
}

Graceful Shutdown Timeout

s, _ := gocron.NewScheduler(gocron.WithStopTimeout(5 * time.Second))
s.NewJob(...)
s.Start()

err := s.Shutdown()
if errors.Is(err, gocron.ErrStopSchedulerTimedOut) {
    log.Println("Some jobs did not finish in time")
}

Task Parameter Mismatch

// Function expects (string, int)
myFunc := func(s string, n int) { fmt.Println(s, n) }

// Wrong number of parameters
_, err := s.NewJob(
    gocron.DurationJob(time.Minute),
    gocron.NewTask(myFunc, "hello"), // missing second parameter
)
if errors.Is(err, gocron.ErrNewJobWrongNumberOfParameters) {
    log.Println("Parameter count mismatch")
}

// Wrong type
_, err = s.NewJob(
    gocron.DurationJob(time.Minute),
    gocron.NewTask(myFunc, "hello", "world"), // second param should be int
)
if errors.Is(err, gocron.ErrNewJobWrongTypeOfParameters) {
    log.Println("Parameter type mismatch")
}

Start Time After Stop Time

start := time.Now().Add(2 * time.Hour)
stop := time.Now().Add(1 * time.Hour)

_, err := s.NewJob(
    gocron.DurationJob(time.Minute),
    gocron.NewTask(myFunc),
    gocron.WithStartAt(gocron.WithStartDateTime(start)),
    gocron.WithStopAt(gocron.WithStopDateTime(stop)),
)
if errors.Is(err, gocron.ErrStartTimeLaterThanEndTime) {
    log.Println("Start time must be before stop time")
}

tessl/golang-github-com-go-co-op-gocron-v2

errors.mddocs/api/

Error Reference

Import

Complete Error List

Error Handling Pattern

Errors by Category

Scheduler Lifecycle Errors

Job Management Errors

Task Validation Errors

Panic Recovery

CronJob Errors

DurationJob Errors

DurationRandomJob Errors

DailyJob Errors

WeeklyJob Errors

MonthlyJob Errors

OneTimeJob Errors

Event Listener Errors

Job Lifecycle Errors

Scheduler Option Errors

Which Functions Return Which Errors

Common Error Scenarios

Invalid Cron Expression

Job Not Found After Removal

Graceful Shutdown Timeout

Task Parameter Mismatch

Start Time After Stop Time

See Also

tessl/golang-github-com-go-co-op-gocron-v2

errors.md.css-3qkkll{font-size:var(--chakra-font-sizes-sm);font-weight:var(--chakra-font-weights-normal);color:var(--chakra-colors-gray-300);}docs/api/

Error Reference

Import

Complete Error List

Error Handling Pattern

Errors by Category

Scheduler Lifecycle Errors

Job Management Errors

Task Validation Errors

Panic Recovery

CronJob Errors

DurationJob Errors

DurationRandomJob Errors

DailyJob Errors

WeeklyJob Errors

MonthlyJob Errors

OneTimeJob Errors

Event Listener Errors

Job Lifecycle Errors

Scheduler Option Errors

Which Functions Return Which Errors

Common Error Scenarios

Invalid Cron Expression

Job Not Found After Removal

Graceful Shutdown Timeout

Task Parameter Mismatch

Start Time After Stop Time

See Also

errors.mddocs/api/