What exit code does timeout return when it kills the command?

124 when the command was still running at the deadline and timeout sent SIGTERM. If you used -k and the command ignored SIGTERM, timeout sends SIGKILL after the grace period and the exit code becomes 137 (128 + signal 9). If the command finishes on its own before the deadline, you get the command's own exit code, untouched. So a successful, fast mysqldump returns 0; a slow one returns 124; a wedged one returns 137. The Bash Exit Code Lookup tool decodes any of these.

What does the -k option do?

-k sets a kill-after grace period. By default timeout sends SIGTERM, which a well-behaved program catches and uses to clean up and exit. But a process stuck in uninterruptible I/O (disk or NFS), or one that traps and ignores SIGTERM, won't die. `timeout -k 20s 5m cmd` says: at 5 minutes send SIGTERM; if it's still alive 20 seconds later, send SIGKILL, which the kernel enforces and nothing can ignore. Without -k, a wedged process survives the timeout entirely.

How do I put a timeout on a whole pipeline or several commands?

timeout runs a single command, so wrap the pipeline in a shell: `timeout 30s bash -c 'curl -s https://api.example.com | jq .status'`. timeout then signals that bash, which carries the pipeline. The same trick works for a sequence: `timeout 2m bash -c 'cmd1 && cmd2'`. Without the bash -c wrapper, timeout only sees the first word as the command and the rest as arguments to it.

Does timeout kill the child processes my command spawned?

It signals the command it launched. If that command spawns children in the same process group and they exit when their parent does, they go too. But a command that double-forks or detaches its children can leave them running after timeout kills the parent. For those, run the work in its own session and signal the whole group — or simpler, prefer commands that manage their own children, and add tool-level timeouts (curl --max-time, ssh -o ConnectTimeout) so individual network calls can't hang in the first place.

Why use timeout if curl already has --max-time?

Use both. A tool's own timeout (curl --max-time, ssh ConnectTimeout, mysqldump's net_read_timeout) is the graceful, specific limit — it knows what it's bounding and can fail cleanly. timeout is the outer hard stop that catches everything the tool's own limits miss: a hang inside a code path the tool author never timed out, a child process gone rogue, an I/O wait the tool can't interrupt. Belt and suspenders. The inner one usually fires; the outer one saves you the night it doesn't.

Stop a Hung Command with timeout

A command under cron can hang forever, and nothing will tell you. A nightly mysqldump that hits a long-held database lock — a runaway analytics query will do it — opens its transaction and sits there waiting, not failing, not logging, not exiting. There is no error in any log, no failed-job alert, no bounced cron mail, because the job never gets far enough to produce any of them. And if the job is sensibly wrapped in a lock so two dumps can't run at once, the hang compounds: every subsequent night's run sees the lock still held by the zombie and skips quietly, so one hung run becomes an outage that lasts until a human goes looking for a backup and finds a dump process that has been "running" since the hang began.

The lesson is blunt: under cron, a hung command is worse than a failed one. A failed command exits, frees its lock, and the next run tries again. A hung command exits never. It holds resources, blocks its own future runs, and produces exactly zero signal because it never gets far enough to log anything. You cannot rely on a command to bound its own runtime — the whole problem is that it's stuck somewhere it can't time itself out of.

So bound it from the outside.

Bounding the runtime

bash

#!/bin/bash
# Script: bounded-dump.sh
# Purpose: Stop a hung command from running forever and jamming the cron slot
# Usage: bounded-dump.sh
set -euo pipefail

CHECK="✓"
CROSS="✗"

# Longer than the job's normal worst case, well under its cron interval.
MAX_RUNTIME="5m"
# After SIGTERM, wait this long, then SIGKILL — for processes wedged in I/O.
KILL_GRACE="20s"

DEST="/backup/mydb.sql"

# In an `if` so set -e doesn't abort before we read the exit code.
# Write to a .partial file so a timed-out run never leaves a corrupt "backup".
if timeout -k "$KILL_GRACE" "$MAX_RUNTIME" \
        mysqldump --single-transaction mydb > "$DEST.partial"; then
    mv "$DEST.partial" "$DEST"
    echo "$CHECK dump completed within $MAX_RUNTIME"
else
    code=$?
    rm -f "$DEST.partial"
    case "$code" in
        124) echo "$CROSS dump exceeded $MAX_RUNTIME and was terminated (SIGTERM)" >&2 ;;
        137) echo "$CROSS dump ignored SIGTERM and was force-killed (SIGKILL)" >&2 ;;
        *)   echo "$CROSS dump failed with exit code $code" >&2 ;;
    esac
    exit "$code"
fi

timeout -k "$KILL_GRACE" "$MAX_RUNTIME" mysqldump ... is the entire mechanism. At five minutes, timeout sends the dump a SIGTERM. A well-behaved program treats SIGTERM as "wrap up and exit." But the dump from my outage wasn't misbehaving — it was blocked in the kernel waiting on a lock, and a process in that state can't act on SIGTERM. That's what -k 20s is for: twenty seconds after the polite signal, timeout sends SIGKILL, which the kernel enforces unconditionally. Nothing survives SIGKILL.

Reading what happened

The exit code is the difference between a useful log and a mystery. 124 means the command was still running at the deadline. 137 is 128 + 9 — it had to be force-killed because it ignored the first signal. Any other non-zero code is the command's own failure, and you should treat it differently. Collapsing all three into "backup failed" throws away the one piece of information that tells you whether you have a slow database, a wedged one, or a broken dump command. (If you ever forget which code means what, the Bash Exit Code Lookup decodes 124 and 137 directly.)

One exception to know about on Ubuntu 26.04: its default timeout is the Rust uutils rewrite, and with timeout -s KILL it exits 124, where GNU timeout exits 137. The -k escalation this script uses is unaffected: a command that ignores SIGTERM exited 137 under both in an ubuntu:26.04 container. But if you match on 137 after -s KILL, accept 124 too. Rust Coreutils vs GNU: What Breaks Scripts has the side-by-side run.

The .partial dance matters more than it looks. If you redirect straight to the real backup file and the command times out mid-write, you've replaced last night's good backup with a half-written, unrestorable file — and you won't know until you need it. Writing to a temp path and mv-ing only on a clean exit means a failed or timed-out run leaves the previous good backup untouched.

For commands that talk to the network, add the tool's own timeout as well — curl --max-time, ssh -o ConnectTimeout, a net_read_timeout on the dump. Those fire first and fail cleanly. timeout is the outer hard stop for the night the inner one doesn't.

A timeout is what makes a lock safe. Locking a job to a single instance with flock stops overlap, but a hang inside the locked job holds that lock forever — which is precisely how my nine-day gap happened. Bound the runtime and the lock always gets released, on time, every time. The two together, plus retrying transient failures with backoff, are the core of an unattended job that fails loudly instead of disappearing. The Hardened Cron Wrapper Generator composes all three, and Bash Scripts That Survive Cron walks the whole decision.

If you want to reproduce the hang safely, a $4 droplet, a deliberately slow sleep 999, and a timeout 5s is the cheapest way to watch all three exit codes for yourself. More of the library is at bashsnippets.xyz, including killing a runaway process by name when a hang escapes the timeout entirely.

Stop a Hung Command with timeout

Bounding the runtime

Reading what happened

The Production Bash Toolkit

Get the bashlib starter

Related Snippets

Frequently Asked Questions