PowerShell スクリプトのエラーと Task Scheduler の終了コード
PowerShell スクリプトは赤いエラーを表示しているのに、Task Scheduler には 0x0 と表示される。あるいは、スクリプトが何を返しても、失敗はすべて 0x1 と表示される。どちらも、powershell.exe がスクリプトのエラーを終了コードに変える仕組みから来ています。ルールがわかれば、本当の結果を報告するのは簡単です。
PowerShell が終了コードを決める仕組み
powershell.exe(Windows PowerShell 5.1)と pwsh(PowerShell 7)についての Microsoft のドキュメントには、スクリプトの起動方法が 2 つ書かれていて、動作が異なります。
-File script.ps1:終了コードはexitに渡した数値です。スクリプトが普通に終われば 0 です。終了エラー(throw、または-ErrorAction Stop付きで実行したコマンドレット)が捕まえられなかった場合は 1 です。-Command "…":exitを呼ばない限り、終了コードは最後のコマンドが成功したかどうか($?)による 0 か 1 です。ほかのコード、たとえば実行したプログラムが返した 3 は 1 に潰されます。Microsoft は、それを残すためにexit $LASTEXITCODEで終えることを勧めています。
落とし穴は 3 種類目のエラーです。コマンドレットの失敗のほとんどは非終了エラーです。存在しないファイルへの Copy-Item、間違ったクエリでの Invoke-Sqlcmd、Write-Error は赤いメッセージを表示するだけで、スクリプトは続行します。-File では、こうしたエラーが 10 個あったスクリプトでも 0 で終了し、Task Scheduler には 0x0 と表示されます。
ネイティブのプログラムにはもう一つルールがあります。スクリプトが .exe を実行すると、その終了コードは $LASTEXITCODE に入り、チェックしない限り、プログラムが失敗してもスクリプトは止まりません。
スクリプトを正しく失敗させる
スクリプトの先頭で、すべてのエラーを終了エラーにし、ネイティブのプログラムは明示的にチェックします。
$ErrorActionPreference = 'Stop' # every cmdlet error now stops the script (exit code 1 with -File)
& C:\tools\export.exe --day today
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
exit に渡したコードが残るように、-Command ではなく -File で起動してください。
結果を TaskBeacon に報告する
これで終了コードは正直になりましたが、まだ誰かが Task Scheduler を見る必要があります。下のラッパーは、powershell.exe -File your-script.ps1 を含むどんなプログラムでも実行し、その終了コードを出力の最後の 20 行と一緒に TaskBeacon に送ります。/0 は OK、それ以外は失敗です。
# Save as C:\jobs\taskbeacon-run.ps1
# Task Scheduler > Action: Start a program
# Program: powershell.exe
# Arguments: -NoProfile -ExecutionPolicy Bypass -File C:\jobs\taskbeacon-run.ps1 "C:\path\to\program.exe" "arg1" "arg2"
# Runs the program, then reports success or failure from its exit code.
# A .ps1 script as the program is run with powershell.exe -NoProfile -ExecutionPolicy Bypass -File script.ps1
# (an execution policy set by Group Policy still wins over Bypass).
$tb = "https://taskbeacon.io/ping/your-job-id"
$program, $programArgs = $args
# a .ps1 file is not a program Windows can start on its own ("not a valid Win32 application")
if ($program -match '\.ps1$') {
$programArgs = @('-NoProfile', '-ExecutionPolicy', 'Bypass', '-File', $program) + @($programArgs | Where-Object { $null -ne $_ })
$program = 'powershell.exe'
}
function Send-TaskBeacon($path, $text) {
$send = @{ UseBasicParsing = $true; TimeoutSec = 10; Uri = ($tb + $path) }
if ($text) { $send.Method = 'Post'; $send.ContentType = 'text/plain; charset=utf-8'; $send.Body = [Text.Encoding]::UTF8.GetBytes($text) }
try { Invoke-WebRequest @send | Out-Null }
catch { Write-Host "TaskBeacon ping failed: $_" }
}
Send-TaskBeacon "/start"
# keep arguments that contain spaces together
$argLine = ($programArgs | ForEach-Object { if ($_ -eq '' -or $_ -match '[\s"]') { '"' + ($_ -replace '"', '\"') + '"' } else { $_ } }) -join ' '
# Windows PowerShell 5.1 refuses an empty -ArgumentList: pass it only when there are arguments
$run = @{ FilePath = $program; Wait = $true; PassThru = $true; NoNewWindow = $true; ErrorAction = 'Stop' }
if ($argLine) { $run.ArgumentList = $argLine }
# the program's output goes to temporary files: shown below, and its last 20 lines go with a failure
$out = [IO.Path]::GetTempFileName(); $err = [IO.Path]::GetTempFileName()
$run.RedirectStandardOutput = $out; $run.RedirectStandardError = $err
$code = 1
$note = ''
try {
$p = Start-Process @run
if ($null -ne $p.ExitCode) { $code = $p.ExitCode }
} catch { $note = "Could not start ${program}: $_"; Write-Host $note }
Get-Content -LiteralPath $out, $err -ErrorAction SilentlyContinue
$tail = ''
if ($code -ne 0) {
$lines = @(Get-Content -LiteralPath $out, $err -Tail 20 -ErrorAction SilentlyContinue) + @($note)
$tail = ($lines | Where-Object { $_ } | ForEach-Object { if ($_.Length -gt 300) { $_.Substring(0, 300) } else { $_ } }) -join "`n"
}
# the exit code goes at the end of the address: /0 = OK, any other number = failed
Send-TaskBeacon "/$code" $tail
Remove-Item -LiteralPath $out, $err -ErrorAction SilentlyContinue
exit $code # not 0 when it failed, so Task Scheduler shows the failure tooアプリでは、ジョブの Code(コード)タブに、your-job-id の代わりにそのジョブ自身のアドレスが入ったこのコードが表示されます。不要な部分はチェックを外せます。
PowerShell スクリプトの場合、タスクの引数は -NoProfile -ExecutionPolicy Bypass -File C:\jobs\taskbeacon-run.ps1 powershell.exe -NoProfile -File C:\jobs\nightly.ps1 になります。ラッパーは同じ終了コードで終わるので、Task Scheduler と TaskBeacon の結果が一致します。
変更できないスクリプトの中には、エラーを表示しながら 0 で終了するものもあります。そうしたスクリプトでは、終了時の ping で出力を送り、Fail if the output contains(出力に次を含む場合は失敗)ERROR, Exception のような出力のルールを追加します。出力中の単語をご覧ください。
得られるもの
- Failed(失敗):終了コードと出力の末尾付きで、メール、Slack、Teams、Webhook に。
- Missed(未実行):タスクが予定時刻と猶予時間までに実行されなかった場合。これはどんな終了コードでもわかりません。
- Late(遅延):スクリプトがいつもの所要時間をとうに過ぎてもまだ実行中の場合。たとえば
Read-Hostのような入力待ちや、誰も答えられない確認で止まっているときです。
TaskBeacon を使わない場合
上のように $ErrorActionPreference = 'Stop'、-File、明示的な exit コードを使い、本体を try { … } catch { …; exit 1 } で囲み、catch ブロックからメールライブラリや Teams の Workflows Webhook で自分にメッセージを送ります。これでスクリプト内のエラーは捕まえられます。始まらない実行や止まってしまうスクリプトには、やはりマシンの外にあってシグナルを待つ仕組みが必要です。実行されなかった定期ジョブをご覧ください。
Claude や ChatGPT を TaskBeacon に接続していますか?「昨夜失敗したのは何で、原因は?」と聞けば、あなたのジョブをもとに答えてくれます。その仕組みをご覧ください。
関連ページ
ドキュメント:PowerShell(Task Scheduler) · ping に終了コード · 出力に含まれる単語
- Task Scheduler の Last Run Result は 0x0 なのに、スクリプトは失敗したLast Run Result 0x0 は、起動したプログラムが 0 を返したことしか意味しません。
- Task Scheduler はもうメールを送れません:タスクが失敗したときにアラートを受け取る標準のメール送信操作はなくなり、イベントで起動するタスクは、起きなかった実行を見逃します。
- Database Mail なしで SQL Server Agent ジョブの失敗アラートを受け取るAgent のメール通知には Database Mail、オペレーター、再起動が必要で、実行されなかったジョブについては何も知らせてくれません。
TaskBeacon は無料で始められます。現在はすべての機能が使え、クレジットカードも不要です。ジョブを作成してコードを貼り付ければ、最初の ping がジョブのページに表示されます。
無料で始める ライブデモを見る出典
- Microsoft Learn:about_PowerShell_exe(Windows PowerShell 5.1、-File と -Command の終了コード) (2024-07-23)
- Microsoft Learn: about_Pwsh (PowerShell 7.5) (2026-01-18)
- Microsoft Learn: about_Automatic_Variables ($LASTEXITCODE) (2026-04-02)
- Microsoft Q&A: Getting PowerShell return code 2147942401 (2022年12月27日、古い:需要の表れ)
このページは 2026年11月9日 に出典と照合しました。他社製品のメニューや制限は変わります。ここに書かれていることが合わなくなっていたら、support@taskbeacon.io までお知らせください。