رفع Start Request Repeated Too Quickly در systemd

اگر هنگام اجرای یک سرویس در Linux با خطای Start request repeated too quickly روبه‌رو شده‌اید، معمولاً systemd چند بار تلاش کرده سرویس را اجرا کند اما سرویس بلافاصله Fail شده است. پس از رسیدن تعداد Startها به محدودیت تعیین‌شده، systemd اجرای مجدد را موقتاً متوقف می‌کند تا سرویس وارد یک حلقه بی‌نهایت Restart نشود.

خطای Start Request Repeated Too Quickly یعنی چه؟

systemd برای جلوگیری از Restart شدن بی‌پایان یک سرویس، تعداد دفعات Start را در یک بازه زمانی محدود می‌کند.

دو تنظیم اصلی این رفتار عبارت‌اند از:

مقادیر پیش‌فرض systemd معمولاً از تنظیمات Manager گرفته می‌شوند و در نسخه‌های امروزی systemd مقدار پیش‌فرض سراسری معمولاً ۵ Start در بازه ۱۰ ثانیه است.

برای مثال اگر سرویسی بلافاصله بعد از Start خطا بدهد و در Unit آن این تنظیم وجود داشته باشد:

[Service]
Restart=on-failure
RestartSec=1s

systemd ممکن است در مدت کوتاهی چند بار سرویس را Restart کند و در نهایت پیامی مشابه زیر نمایش دهد:

Start request repeated too quickly.
Failed with result 'exit-code'.
Failed to start myapp.service.

نکته مهم: این پیام معمولاً خطای اصلی نیست

عبارت Start request repeated too quickly بیشتر نتیجه چند Fail متوالی است، نه دلیل اولین Fail.

علت اصلی ممکن است یکی از موارد زیر باشد:

مرحله ۱: وضعیت سرویس را بررسی کنید

اولین فرمان باید Status همان سرویس باشد:

sudo systemctl status SERVICE_NAME --no-pager -l

به‌جای SERVICE_NAME نام واقعی سرویس را وارد کنید.

برای مثال:

sudo systemctl status nginx --no-pager -l

در خروجی به بخش‌های زیر توجه کنید:

مرحله ۲: Log کامل سرویس را بخوانید

برای پیدا کردن اولین خطای واقعی، Journal بسیار مهم‌تر از پیام Start Limit است:

sudo journalctl -u SERVICE_NAME -b -n 100 --no-pager

برای دیدن Logهای جدید به‌صورت زنده:

sudo journalctl -u SERVICE_NAME -f

به‌دنبال اولین Error قبل از پیام Start request repeated too quickly باشید.

مرحله ۳: Unit File واقعی سرویس را بررسی کنید

برای دیدن Unit File به‌همراه Overrideها:

systemctl cat SERVICE_NAME

به‌خصوص این گزینه‌ها را بررسی کنید:

ExecStart=
User=
WorkingDirectory=
Environment=
EnvironmentFile=
Restart=
RestartSec=
StartLimitIntervalSec=
StartLimitBurst=

مرحله ۴: مسیر ExecStart را بررسی کنید

یکی از رایج‌ترین علت‌ها مسیر اشتباه فایل اجرایی است.

فرض کنیم Unit شامل این خط است:

ExecStart=/opt/myapp/app

وجود فایل را بررسی کنید:

ls -l /opt/myapp/app

اگر فایل Script است، Permission اجرایی را نیز بررسی کنید:

sudo chmod +x /opt/myapp/app

مرحله ۵: User سرویس را بررسی کنید

اگر Unit شامل این خط باشد:

User=myapp

بررسی کنید User وجود دارد:

id myapp

همچنین باید به Working Directory و فایل‌های موردنیاز دسترسی داشته باشد.

مرحله ۶: برنامه را با همان User به‌صورت دستی تست کنید

اگر سرویس با User خاصی اجرا می‌شود، برنامه را با همان User تست کنید:

sudo -u myapp /opt/myapp/app

اگر همین‌جا Error دریافت می‌کنید، مشکل از Start Limit نیست؛ برنامه یا دسترسی‌های آن باید اصلاح شود.

مرحله ۷: اشغال بودن Port را بررسی کنید

برای Web Appها، APIها و Proxyها یکی از علت‌های رایج Fail سریع، استفاده سرویس دیگری از همان Port است.

مثلاً برای Port 8080:

sudo ss -lntp | grep ':8080'

اگر Process دیگری در حال Listen است، ابتدا مشخص کنید کدام سرویس باید روی آن Port اجرا شود.

مرحله ۸: Syntax فایل Service را بررسی کنید

اگر Unit اختصاصی ساخته‌اید، قبل از Restart آن را بررسی کنید:

systemd-analyze verify /etc/systemd/system/myapp.service

بعد از هر تغییر در Unit File:

sudo systemctl daemon-reload

مرحله ۹: بعد از رفع خطا Start Limit را Reset کنید

بعد از اینکه علت اصلی Fail را اصلاح کردید، ممکن است systemd هنوز سرویس را در وضعیت Failed و Rate Limited نگه داشته باشد.

برای Reset کردن:

sudo systemctl reset-failed SERVICE_NAME

سپس:

sudo systemctl start SERVICE_NAME
sudo systemctl status SERVICE_NAME --no-pager

دستور reset-failed شمارنده Start Rate Limit سرویس را نیز Reset می‌کند.

مرحله ۱۰: RestartSec را منطقی تنظیم کنید

اگر سرویس بعد از Fail بلافاصله Restart می‌شود، افزایش فاصله بین تلاش‌ها می‌تواند از Restart Loop بسیار سریع جلوگیری کند.

Override بسازید:

sudo systemctl edit SERVICE_NAME

نمونه:

[Service]
Restart=on-failure
RestartSec=5s

بعد از ذخیره:

sudo systemctl daemon-reload
sudo systemctl restart SERVICE_NAME

مرحله ۱۱: تنظیم StartLimitIntervalSec و StartLimitBurst

اگر سرویس واقعاً نیاز دارد چند بار برای Recovery تلاش کند، می‌توانید Rate Limit را متناسب با رفتار سرویس تنظیم کنید.

نمونه:

[Unit]
StartLimitIntervalSec=60s
StartLimitBurst=5

[Service]
Restart=on-failure
RestartSec=5s

این تنظیم یعنی حداکثر پنج Start در یک بازه ۶۰ ثانیه مجاز است.

اگر سرویس بیشتر از این تعداد Fail کند، systemd اجرای خودکار بیشتر را محدود می‌کند.

آیا StartLimitIntervalSec=0 درست است؟

systemd اجازه می‌دهد Rate Limit را با مقدار صفر غیرفعال کنید:

[Unit]
StartLimitIntervalSec=0

نمونه Unit File استاندارد برای یک سرویس ساده

یک نمونه متعادل می‌تواند به شکل زیر باشد:

[Unit]
Description=My Application
After=network.target
StartLimitIntervalSec=60s
StartLimitBurst=5

[Service]
Type=simple
User=myapp
WorkingDirectory=/opt/myapp
ExecStart=/opt/myapp/app
Restart=on-failure
RestartSec=5s

[Install]
WantedBy=multi-user.target

این فقط نمونه است. User، مسیرها، Dependency و Restart Policy باید مطابق برنامه واقعی تنظیم شوند.

اگر Environment Variable مشکل داشته باشد

برنامه ممکن است در SSH درست اجرا شود اما در systemd Fail شود، چون Environment شل شما به‌صورت خودکار وارد سرویس نمی‌شود.

Unit را بررسی کنید:

Environment=APP_ENV=production
EnvironmentFile=/etc/myapp/myapp.env

وجود فایل Environment و Permission آن را بررسی کنید:

sudo ls -l /etc/myapp/myapp.env

اگر سرویس به شبکه وابسته است

اگر برنامه بلافاصله هنگام Boot به دیتابیس Remote، API یا اینترنت وصل می‌شود، ممکن است قبل از آماده‌شدن اتصال شبکه Fail شود.

برای سرویس‌هایی که واقعاً به شبکه آماده نیاز دارند:

[Unit]
Wants=network-online.target
After=network-online.target

این تنظیم را فقط زمانی اضافه کنید که سرویس واقعاً به Online بودن شبکه وابسته است.

چطور تنظیمات Start Limit فعلی را ببینیم؟

برای مشاهده مقادیر مؤثر یک Unit:

systemctl show SERVICE_NAME | grep -E 'StartLimit|Restart'

همچنین Unit و Overrideهای فعلی را ببینید:

systemctl cat SERVICE_NAME

ترتیب صحیح رفع Start Request Repeated Too Quickly

یک دستور سریع برای Reset خطا

اگر علت اصلی را قبلاً رفع کرده‌اید، این سه فرمان معمولاً برای خروج از وضعیت Rate Limited کافی هستند:

sudo systemctl reset-failed SERVICE_NAME
sudo systemctl start SERVICE_NAME
sudo systemctl status SERVICE_NAME --no-pager

پرسش‌های متداول

Start request repeated too quickly یعنی چه؟

یعنی یک Unit در یک بازه کوتاه بیش از تعداد مجاز Start شده و systemd برای جلوگیری از Restart Loop، Startهای بعدی را محدود کرده است.

چطور این وضعیت را Reset کنیم؟

بعد از رفع علت اصلی، از systemctl reset-failed SERVICE_NAME استفاده کنید. این فرمان وضعیت Failed و شمارنده Start Rate Limit را Reset می‌کند.

آیا افزایش StartLimitBurst مشکل را حل می‌کند؟

فقط زمانی مفید است که سرویس به‌طور طبیعی به چند تلاش Recovery نیاز داشته باشد. اگر سرویس به‌دلیل Config اشتباه یا Crash دائمی Fail می‌شود، افزایش Burst فقط خطا را به تأخیر می‌اندازد.

آیا StartLimitIntervalSec=0 پیشنهاد می‌شود؟

معمولاً خیر. مقدار صفر Rate Limiting را غیرفعال می‌کند و یک سرویس خراب ممکن است وارد Restart Loop دائمی شود.

RestartSec چه کاری انجام می‌دهد؟

فاصله بین تلاش‌های Restart خودکار را تعیین می‌کند. افزایش منطقی آن می‌تواند از Restartهای بسیار سریع جلوگیری کند.

بعد از تغییر Unit File باید Reboot کنیم؟

خیر. معمولاً اجرای systemctl daemon-reload و سپس Restart سرویس کافی است.

چرا برنامه دستی اجرا می‌شود ولی در systemd Fail می‌شود؟

ممکن است User، WorkingDirectory، Environment Variable، PATH یا Permission در محیط systemd با Shell شما متفاوت باشد. Unit File و Journal را بررسی کنید.

منابع

🔹 systemd.unit؛ StartLimitIntervalSec و StartLimitBurst

🔹 systemctl؛ reset-failed و مدیریت سرویس‌ها

🔹 مستندات systemd.service و RestartSec