Errores de scripts de PowerShell y el código de salida en Task Scheduler
Tu script de PowerShell muestra errores en rojo, pero Task Scheduler muestra 0x0; o cada fallo aparece como 0x1, devuelva lo que devuelva el script. Ambas cosas vienen de cómo powershell.exe convierte los errores de un script en un código de salida. Una vez que conoces las reglas, es fácil reportar el resultado real.
Cómo decide PowerShell el código de salida
La documentación de Microsoft para powershell.exe (Windows PowerShell 5.1) y pwsh (PowerShell 7) describe dos formas de iniciar un script, y se comportan de manera distinta:
-File script.ps1: el código de salida es el número que pasas aexit. Si el script termina normalmente, es 0. Si un error terminante (unthrow, o un cmdlet ejecutado con-ErrorAction Stop) no se captura, es 1.-Command "…": el código de salida es 0 o 1, según si el último comando tuvo éxito ($?), a menos que llames aexit. Cualquier otro código, por ejemplo un 3 de un programa que ejecutaste, se reduce a 1. Microsoft sugiere terminar conexit $LASTEXITCODEpara conservarlo.
La trampa es el tercer tipo de error. La mayoría de los fallos de cmdlets son no terminantes: Copy-Item sobre un archivo que no existe, Invoke-Sqlcmd con una consulta errónea o Write-Error muestran un mensaje en rojo y el script sigue. Con -File, un script que tuvo diez de esos igual termina con 0, y Task Scheduler muestra 0x0.
Los programas nativos añaden una regla más: cuando tu script ejecuta un .exe, su código de salida está en $LASTEXITCODE, y un programa que falla no detiene el script a menos que lo compruebes.
Haz que el script falle como corresponde
Al principio del script, convierte todos los errores en terminantes y comprueba explícitamente los programas nativos:
$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 }
Inícialo con -File, no con -Command, para que el código que pasas a exit se conserve.
Reporta el resultado a TaskBeacon
Ahora el código de salida es honesto, pero alguien todavía tiene que mirar Task Scheduler. El wrapper de abajo ejecuta cualquier programa, incluido powershell.exe -File your-script.ps1, y envía su código de salida a TaskBeacon: /0 es OK, cualquier otro valor, un fallo, junto con las últimas 20 líneas de la salida.
# 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 tooEn la app, la pestaña Code (código) de tu job te da este código con la dirección propia del job en lugar de your-job-id, y puedes desmarcar las partes que no necesites.
Para un script de PowerShell, los argumentos de la tarea pasan a ser -NoProfile -ExecutionPolicy Bypass -File C:\jobs\taskbeacon-run.ps1 powershell.exe -NoProfile -File C:\jobs\nightly.ps1. El wrapper termina con el mismo código de salida, así que Task Scheduler coincide con TaskBeacon.
Algunos scripts no se pueden cambiar y muestran errores mientras terminan con 0. Para esos, envía la salida con el ping de fin y añade una regla de salida como Fail if the output contains (fallar si la salida contiene) ERROR, Exception; consulta Palabras en la salida.
Qué obtienes
- Failed (fallido) con el código de salida y el final de la salida, por correo, Slack, Teams o un webhook.
- Missed (no ejecutado) cuando la tarea no se ejecutó antes de su hora prevista más el margen, algo que ningún código de salida te puede decir.
- Late (retrasado) cuando el script sigue ejecutándose mucho después de su duración habitual, por ejemplo atascado en un aviso como
Read-Hosto en una confirmación que nadie puede responder.
Sin TaskBeacon
Usa $ErrorActionPreference = 'Stop', -File y códigos de exit explícitos como arriba, envuelve el cuerpo en try { … } catch { …; exit 1 } y envíate un mensaje desde el bloque catch con una biblioteca de correo o un webhook de Teams Workflows. Eso detecta los errores dentro del script. Las ejecuciones que nunca empiezan y los scripts que se cuelgan siguen necesitando algo fuera de la máquina que espere una señal; consulta una tarea programada que no se ejecutó.
¿Conectaste Claude o ChatGPT a TaskBeacon? Pregúntale “¿qué falló anoche y por qué?” y te responde a partir de tus jobs. Cómo funciona.
Relacionado
En la documentación: PowerShell (Task Scheduler) · Código de salida en el ping · Palabras en la salida.
- Task Scheduler Last Run Result 0x0, pero el script fallóLast Run Result 0x0 solo significa que el programa que inició devolvió 0.
- El Programador de tareas ya no puede enviar correos: recibe una alerta cuando una tarea fallaLa acción integrada de correo ya no existe; las tareas activadas por eventos no detectan ejecuciones que nunca ocurrieron.
- Alertas de fallo de jobs de SQL Server Agent sin Database MailLos correos de Agent necesitan Database Mail, un operador y un reinicio, y no dicen nada de una tarea que no se ejecutó.
Todos los casos de uso · Preguntas frecuentes
Empezar con TaskBeacon es gratis, por ahora con todas las funciones abiertas y sin tarjeta de crédito. Crea un job, pega el código y el primer ping aparece en la página del job.
Empieza gratis Ver demo en vivoFuentes
- Microsoft Learn: about_PowerShell_exe (Windows PowerShell 5.1, códigos de salida de -File y -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 de diciembre de 2022, antiguo: señal de demanda)
Página revisada contra sus fuentes el 9 de noviembre de 2026. Los menús y límites de otros productos cambian; si algo aquí ya no coincide, escribe a support@taskbeacon.io.