Running and Debugging#
Every execution of a job is a run. GearTrain records each run with its status, duration, and console output, so you can see what your jobs did and why. This guide covers running jobs on demand, watching the live console, reading run history when something goes wrong, and how failed runs are retried and handled.
Ways To Run a Job#
- On schedule. The job’s cron expression decides when it runs. See Writing Jobs.
- On demand. Click Run now on a job to start a run immediately. This is the fastest way to test changes: edit the script in the workbench, click Run now, and watch the result.
Both kinds of runs appear in the same history. There is no separate test concept; a manual run is a real run.
Watch the Live Console#
When you open a running run, its console updates in place. Everything
the script logs with console.log, console.info, console.warn, and
console.error streams in as it happens, so you can follow a long job
without waiting for it to finish.
When the run completes, the console stays available. The output of every run is kept, not just the live view.
Run History#
The Runs page lists all runs across your jobs, newest first. Each entry shows the job, the start time, the duration, and a status badge:
| Status | Meaning |
|---|---|
| Running | The script is still executing |
| Success | The script finished without throwing |
| Error | The script threw an uncaught error |
| Timeout | The script exceeded its time limit |
| Retrying | An attempt failed and will be tried again |
| Interrupted | A run stopped by a restart; it is retried |
Open any run to see its full console output and details. You can also filter the list by job or by status, and delete runs you no longer need.
Reading Failures#
When a run ends with Error, its console shows the thrown error, with
the message and the place it was thrown. Open the run, read the error,
and fix the script in the workbench. For example, a name that no secret
or environment variable provides fails right at the env.get call with
a clear error.
Timeout means the script hit its time limit. See Limits below.
For error-handling patterns in your scripts, see Best Practices.
Retries and Failure Handling#
A scheduled run that fails is retried automatically before GearTrain records the failure.
Attempts and Retries#
A job’s Attempts setting (1 to 5, default 3) is the total number of times a scheduled run is attempted. When an attempt fails, the next one runs after a short backoff:
| Failed attempt | Wait before the next attempt |
|---|---|
| 1 | 1 minute |
| 2 | 5 minutes |
| 3 and later | 15 minutes |
Every attempt counts toward your monthly run limit and gets its own console section on the run page. Manual runs are never retried: when you click Run now and the script fails, the run ends there.
When a Run Fails#
When every attempt fails, the run ends with Error (the script threw) or Timeout (it exceeded a limit). GearTrain can email you the error and a link to the run.
Automatic Pause#
A job that keeps failing would keep spending your run limit. After 3 consecutive failed runs, GearTrain pauses the schedule and emails you. The job and its history stay intact; click Resume on the Jobs page to turn the schedule back on, which resets the failure count.
The attempt count, failure emails, and auto-pause are each set per job on its edit page.
Limits#
Each run operates within limits that depend on your plan: compute time, total run time, and memory. A run that exceeds a time limit ends with the Timeout status. The table in The Sandbox lists the values for the free plan.
If your job regularly times out, have each run do less: process items incrementally, resuming where the previous run stopped, or split the work across separate jobs. See Best Practices.