What the message looks like
myapp.service: Start request repeated too quickly.
myapp.service: Failed with result 'start-limit-hit'.
Failed to start myapp.service - My application.Common causes
- The program exits right after start: wrong config, missing file, permission problem or a port that is already in use.
Restart=alwayswith a very shortRestartSecrestarts a broken service too often.- A dependency (database, mount, network) is not ready yet.
- More than 5 starts within 10 seconds, the defaults of
StartLimitBurstandStartLimitIntervalSec. - A bad update changed a binary or a configuration.
Check
- State and last lines of the unit
systemctl status myapp --no-pager - Why did it crash? Read the journal of the unit
- The limits that apply to this unit
systemctl show myapp -p Restart -p RestartUSec -p StartLimitBurst -p StartLimitIntervalUSec
Fix
- Find and fix the real error in the journal first (config, permission, port, dependency).
- Clear the failed state:
systemctl reset-failed myapp, thensystemctl start myapp. - Give the service breathing room:
RestartSec=5in[Service]and, if needed,StartLimitIntervalSec=60andStartLimitBurst=5in[Unit]. - Add
After=andRequires=for dependencies that must be ready first. - Run
systemctl daemon-reloadafter editing the unit file.
Typical scenario
You set up a Node.js app as a systemd service with Restart=always and no RestartSec. After a deployment the .env file is missing, the program exits at once with code 1, and after five starts in ten seconds the status reads "failed (Result: start-limit-hit)". The service refuses to start even though you added the file. First read the reason for the first crash with journalctl -u myapp -n 50.
FAQ
Can I just raise the start limit?
You can, but it only hides a crash loop. First find out why the process exits. Raise the limit only for a service that is meant to restart often.
How do I see all failed units?
Run systemctl --failed.
Why does systemctl start still fail after I fixed the cause?
The failed state with the start limit stays until you reset it. Run systemctl reset-failed myapp and start again. Without the reset, systemd keeps refusing further starts even though the cause is long gone.
What are the default values of the start limit?
On most distributions it is five starts within ten seconds, controlled by StartLimitBurst and StartLimitIntervalSec. The global defaults sit in systemd's system.conf and can be overridden per unit. The global defaults sit in systemd's system.conf as DefaultStartLimitIntervalSec and DefaultStartLimitBurst.
Which section of the unit do the StartLimit options belong in?
In [Unit], not in [Service]. Putting them in the wrong section gives a warning or they do not work as expected. Restart= and RestartSec=, however, belong in [Service]. After edits you need systemctl daemon-reload.