Get an alert when a Stata do-file fails in batch mode
You run a do-file every night in Stata batch mode, it stops on an error, and Task Scheduler still says The operation completed successfully (0x0). Nobody hears about it until someone opens the report. Stata batch mode hides the error from the scheduler, but the do-file itself can report it, with Stata's r() code.
Why the scheduler thinks it worked
On Windows, Stata runs a do-file without a window with StataMP-64.exe /e do job.do (/b also works, but waits for you to click OK at the end, which a schedule can't do). On Linux and macOS the equivalent is stata -b do job.do. Either way Stata writes the output to job.log, and when the do-file stops at an error, the error is in that log: a line such as r(601);.
The process itself, though, ends normally. Stata users have reported for years, on Windows, Linux and macOS, that batch mode returns exit code 0 after an error (we saw the same on Stata 17 MP for Windows with /e), and StataCorp's batch-mode FAQs say nothing about exit codes. A scheduler can only judge a job by its exit code, so Task Scheduler shows 0x0 and cron sees success. The usual workaround is to search the log for r( afterwards, which works until the log lands in a folder you didn't expect.
Two more ways a Stata job goes quiet: the task never starts (the PC was off or asleep, or the task's account can't log on), and Stata waits on a dialog instead of exiting, which some users have seen even in batch mode. Neither one produces a log line you would notice.
Report the error from inside the do-file
The fix is to let the do-file catch its own error and report it, instead of relying on the exit code. The code below wraps your work in capture noisily { … }. If anything inside fails, it sends /fail with the return code (for example rc=601, file not found) and, if you set tb_log to the do-file's log, its last 20 lines. Then it stops with the same error. On Windows, Stata still exits with 0 in batch mode (we ran this code on Stata 17 MP with /e: the pings arrived, and Windows saw exit code 0 after r(601)), so the alert is what tells you, not Task Scheduler. When the do-file ends well, it sends the number of observations in memory.
* --- TaskBeacon: top of the do-file ---
local tb "https://taskbeacon.io/ping/your-job-id"
* curl.exe is built into Windows 10 and 11; macOS and Linux have curl
local tb_curl = cond(c(os) == "Windows", "curl.exe", "curl")
local tb_log "" // optional: this do-file's log (batch mode: stata -b do job.do, or StataMP-64.exe /e do job.do on Windows, writes job.log in the current folder); its last 20 lines go with a failure
shell `tb_curl' -fsS -m 10 "`tb'/start"
capture noisily {
* --- your code here (the example data: replace with your own) ---
sysuse auto, clear
}
quietly {
local tb_rc = _rc
if `tb_rc' {
* the last 20 lines of the log (if tb_log is set) go with the failure
local tb_data ""
if `"`tb_log'"' != "" {
tempfile tb_tail
tempname tb_in tb_out
capture {
file open `tb_in' using `"`tb_log'"', read text
local tb_n 0
file read `tb_in' tb_line
while r(eof) == 0 {
local tb_n = `tb_n' + 1
local tb_k = mod(`tb_n', 20)
local tb_l`tb_k' = substr(`"`macval(tb_line)'"', 1, 300)
file read `tb_in' tb_line
}
file close `tb_in'
file open `tb_out' using `"`tb_tail'"', write text replace
forvalues tb_i = `=max(1, `tb_n' - 19)'/`tb_n' {
local tb_k = mod(`tb_i', 20)
file write `tb_out' `"`macval(tb_l`tb_k')'"' _n
}
file close `tb_out'
local tb_data `"--data-binary "@`tb_tail'" -H "Content-Type: text/plain""'
}
capture file close `tb_in'
capture file close `tb_out'
}
shell `tb_curl' -fsS -m 10 `tb_data' "`tb'/fail?rc=`tb_rc'"
exit `tb_rc'
}
}
* --- TaskBeacon: end of the do-file ---
local tb_rows = _N
shell `tb_curl' -fsS -m 10 "`tb'?rows=`tb_rows'"In the app, the Code tab of your job gives you this code with the job's own address instead of your-job-id, and you can untick the parts you don't need.
Put everything that can fail between the braces: a command after the closing brace isn't caught. The pings use curl.exe, which is part of Windows 10 and 11, and wait at most 10 seconds, so a network problem never stops your do-file. The code is written for Stata on Windows; on Linux or macOS, write curl instead of curl.exe.
What you get
- Failed, right away, with the
r()code and the end of the log in the alert. Seeingr(601)and the file name in your inbox is usually enough to know what to fix. - Missed when the do-file didn't report by its planned time plus a grace period, for example because the PC was off. You set the schedule on the job like in Task Scheduler.
- Late when the start ping came but the run is taking much longer than usual, which is what a do-file stuck on a dialog looks like.
- Odd data when it finished but
_Nfell more than 40% below the recent runs, or is 0. See 0 rows or far fewer than usual.
To schedule the do-file, set the task's Start in folder to the do-file's folder so the log is written where you can find it (otherwise Stata may try its program folder and stop with r(608)). The Stata page in the Docs has the full schtasks line.
Without TaskBeacon
You can make the exit code honest yourself: start Stata from a small .bat or shell script, and after Stata ends, search the log for a line that starts with r( followed by digits; if one is found, exit with 1. Task Scheduler then shows 0x1. That covers errors, but not a run that never started or a Stata session waiting on a dialog, and you still have to look at Task Scheduler to see the 0x1. For an email you also need something that sends it, which Task Scheduler no longer does on its own (see email when a scheduled task fails).
Connected Claude or ChatGPT to TaskBeacon? Ask it "what failed last night, and why?" and it answers from your jobs. How that works.
Related
In the Docs: Stata · Statuses · What can be reported.
- Task Scheduler Last Run Result 0x0, but the script failedLast Run Result 0x0 only means the program it started returned 0.
- Get an alert when a job loads 0 rows, or far fewer than usualExit code 0 says nothing about how many rows arrived.
- Find out when a scheduled job didn't run at allA run that never happened leaves no error to alert on.
TaskBeacon is free to start, with every feature open for now and no credit card. Create a job, paste the code, and the first ping shows up on the job page.
Start free View live demoSources
- StataCorp FAQ: Running Stata for Windows in batch mode (/e and /b) (undated, examples use Stata 15; checked 2026-11-09)
- StataCorp FAQ: Running Stata in batch mode on Unix (-b writes file.log) (undated; checked 2026-11-09)
- Statalist archive: a batch file returns 0 although the do-file failed (Windows /e) (2008, old: a sign of a long-standing question)
- Statalist archive: no non-zero exit code after an error in batch mode (macOS) (2011, old: a sign of a long-standing question)
- Statalist: Stata batch mode exit status on error (Stata 13 era, about 2014; old)
- A wrapper that searches the log for r(…); and exits 1 (P. Schumm, GitHub gist) (undated)
Page checked against its sources on 2026-11-09. Menus and limits of other products change; if something here no longer matches, write to support@taskbeacon.io.