Fehler in PowerShell-Skripten und der Exit-Code in der Aufgabenplanung
Ihr PowerShell-Skript gibt rote Fehler aus, aber die Aufgabenplanung (Task Scheduler) zeigt 0x0; oder jeder Fehler erscheint als 0x1, egal was das Skript zurückgegeben hat. Beides kommt daher, wie powershell.exe die Fehler eines Skripts in einen Exit-Code übersetzt. Wenn Sie die Regeln kennen, lässt sich das echte Ergebnis leicht melden.
Wie PowerShell den Exit-Code bestimmt
Die Dokumentation von Microsoft zu powershell.exe (Windows PowerShell 5.1) und pwsh (PowerShell 7) beschreibt zwei Arten, ein Skript zu starten, und sie verhalten sich unterschiedlich:
-File script.ps1: Der Exit-Code ist die Zahl, die Sie anexitübergeben. Endet das Skript normal, ist er 0. Wird ein Abbruchfehler (einthrowoder ein Cmdlet mit-ErrorAction Stop) nicht abgefangen, ist er 1.-Command "…": Der Exit-Code ist 0 oder 1, je nachdem, ob der letzte Befehl erfolgreich war ($?), es sei denn, Sie rufenexitauf. Jeder andere Code, zum Beispiel 3 von einem Programm, das Sie ausgeführt haben, wird auf 1 reduziert. Microsoft schlägt vor, mitexit $LASTEXITCODEzu enden, um ihn zu behalten.
Die Falle ist die dritte Art von Fehler. Die meisten Cmdlet-Fehler sind nicht abbrechend: Copy-Item mit einer fehlenden Datei, Invoke-Sqlcmd mit einer fehlerhaften Abfrage oder Write-Error geben eine rote Meldung aus, und das Skript läuft weiter. Mit -File endet ein Skript, das zehn solcher Fehler hatte, trotzdem mit 0, und die Aufgabenplanung zeigt 0x0.
Native Programme bringen noch eine Regel mit: Wenn Ihr Skript eine .exe ausführt, steht deren Exit-Code in $LASTEXITCODE, und ein fehlschlagendes Programm hält das Skript nicht an, solange Sie das nicht prüfen.
Das Skript richtig fehlschlagen lassen
Machen Sie am Anfang des Skripts jeden Fehler zu einem abbrechenden und prüfen Sie native Programme ausdrücklich:
$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 }
Starten Sie es mit -File, nicht mit -Command, damit der Code, den Sie an exit übergeben, erhalten bleibt.
Das Ergebnis an TaskBeacon melden
Jetzt ist der Exit-Code ehrlich, aber jemand muss immer noch in die Aufgabenplanung schauen. Der Wrapper unten führt ein beliebiges Programm aus, auch powershell.exe -File your-script.ps1, und sendet dessen Exit-Code an TaskBeacon: /0 ist OK, alles andere ein Fehler, zusammen mit den letzten 20 Zeilen der Ausgabe.
# 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 tooIn der App gibt Ihnen der Tab Code Ihres Jobs diesen Code mit der eigenen Adresse des Jobs statt your-job-id, und Sie können die Teile abwählen, die Sie nicht brauchen.
Für ein PowerShell-Skript lauten die Argumente der Aufgabe -NoProfile -ExecutionPolicy Bypass -File C:\jobs\taskbeacon-run.ps1 powershell.exe -NoProfile -File C:\jobs\nightly.ps1. Der Wrapper endet mit demselben Exit-Code, sodass die Aufgabenplanung mit TaskBeacon übereinstimmt.
Manche Skripte lassen sich nicht ändern und geben Fehler aus, während sie mit 0 enden. Senden Sie für diese die Ausgabe mit dem Abschluss-Ping und fügen Sie eine Ausgaberegel hinzu, etwa Fail if the output contains (Fehler, wenn die Ausgabe enthält) ERROR, Exception; siehe Wörter in der Ausgabe.
Was Sie bekommen
- Failed (fehlgeschlagen) mit dem Exit-Code und dem Ende der Ausgabe, per E-Mail, Slack, Teams oder Webhook.
- Missed (verpasst), wenn die Aufgabe bis zu ihrer geplanten Zeit plus Karenzzeit nicht gelaufen ist, was Ihnen kein Exit-Code sagen kann.
- Late (verspätet), wenn das Skript lange nach seiner üblichen Dauer noch läuft, zum Beispiel weil es an einer Eingabeaufforderung wie
Read-Hostoder einer Bestätigung hängt, die niemand beantworten kann.
Ohne TaskBeacon
Verwenden Sie wie oben $ErrorActionPreference = 'Stop', -File und ausdrückliche exit-Codes, umschließen Sie den Hauptteil mit try { … } catch { …; exit 1 } und schicken Sie sich aus dem catch-Block eine Nachricht, mit einer Mail-Bibliothek oder einem Teams-Workflows-Webhook. Das erkennt Fehler innerhalb des Skripts. Läufe, die nie starten, und Skripte, die hängen, brauchen trotzdem etwas außerhalb des Rechners, das ein Signal erwartet; siehe ein geplanter Job, der nicht gelaufen ist.
Claude oder ChatGPT mit TaskBeacon verbunden? Fragen Sie: „Was ist letzte Nacht fehlgeschlagen, und warum?“, und die Antwort kommt aus Ihren Jobs. So funktioniert das.
Verwandte Themen
In den Docs: PowerShell (Aufgabenplanung) · Exit-Code im Ping · Wörter in der Ausgabe.
- Aufgabenplanung zeigt Last Run Result 0x0, aber das Skript ist fehlgeschlagenLast Run Result 0x0 bedeutet nur, dass das gestartete Programm 0 zurückgegeben hat.
- Die Aufgabenplanung kann keine E-Mails mehr senden: Benachrichtigung, wenn eine Aufgabe fehlschlägtDie eingebaute E-Mail-Aktion gibt es nicht mehr; ereignisgesteuerte Aufgaben übersehen Läufe, die nie stattgefunden haben.
- Benachrichtigungen bei fehlgeschlagenen SQL-Server-Agent-Jobs ohne Database MailAgent-E-Mails brauchen Database Mail, einen Operator und einen Neustart und sagen nichts über einen Job, der nicht gelaufen ist.
Der Einstieg in TaskBeacon ist kostenlos, derzeit mit allen Funktionen und ohne Kreditkarte. Legen Sie einen Job an, fügen Sie den Code ein, und der erste Ping erscheint auf der Seite des Jobs.
Kostenlos starten Live-Demo ansehenQuellen
- Microsoft Learn: about_PowerShell_exe (Windows PowerShell 5.1, Exit-Codes bei -File und -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 (27. Dezember 2022, alt: ein Zeichen für Bedarf)
Diese Seite wurde am 9. November 2026 mit ihren Quellen abgeglichen. Menüs und Grenzen anderer Produkte ändern sich; wenn hier etwas nicht mehr stimmt, schreiben Sie an support@taskbeacon.io.