Docker "STOPSIGNAL" - "invalid signal" in the Dockerfile in CI

By Kaveh Alemi·Latchkey

A STOPSIGNAL instruction named a signal Docker does not recognize. The value must be a valid signal name (with or without SIG) or a valid signal number - anything else fails the build.

What this error means

The build (or container create) fails with invalid signal: <value>, naming the STOPSIGNAL you set. It is deterministic - the value is simply not a valid signal.

ERROR: failed to solve: invalid signal: SIGTREM
# STOPSIGNAL SIGTREM   (typo of SIGTERM)
# or an out-of-range number: STOPSIGNAL 99

Common causes

Misspelled or unknown signal name

A typo (SIGTREM) or a non-existent signal name is rejected. Docker validates the value against known signals.

Out-of-range or non-numeric signal number

A numeric STOPSIGNAL must be a valid signal number for the platform. A number outside the valid range fails validation.

How to fix it

Use a valid signal name or number

Set STOPSIGNAL to a real signal - name (with or without SIG) or number.

STOPSIGNAL SIGTERM
# equivalents:
# STOPSIGNAL TERM
# STOPSIGNAL 15

Match STOPSIGNAL to how your app shuts down

Pick the signal your process handles for graceful shutdown.

# if your app traps SIGQUIT for a clean stop:
STOPSIGNAL SIGQUIT

How to prevent it

• Use canonical signal names (SIGTERM, SIGQUIT) or valid numbers.
• Set STOPSIGNAL to a signal your app handles for graceful shutdown.
• Lint Dockerfiles to catch typos in instruction values.

Frequently asked questions

Related guides

References

• Docker documentation
• Docker build cache
• GitHub Actions documentation