Troubleshooting Long-Running Job Stops After Disconnect
A long-running command stops when the terminal closes or the remote session disconnects.
This usually means: The work was tied to the shell session or terminal lifecycle, and the chosen running model was not persistent enough for the real need.
Performance and Memory both medium severity
Start with first checks Confirm how the job was started. Do not assume background means persistent.
Symptom A long-running command stops when the terminal closes or the remote session disconnects.
What this usually means The work was tied to the shell session or terminal lifecycle, and the chosen running model was not persistent enough for the real need.
Meaning of the symptom
The failure is often not the command itself. The failure is the running model.
Safe sequence
- Confirm how the job was started.
- Decide whether you need reconnectability, supervision, or both.
- Recreate the job with the correct model.
- Verify what happens when the session ends.
Common branch decisions
- A quick background job is often enough only when you stay in the same session.
- A remote long-running command usually needs a persistent session.
- A system workload that should restart automatically often belongs under service supervision.
First checks - Confirm how the job was started.
- Decide whether the real need was shell convenience, reconnectability, or supervised service behavior.
- Check whether any output, logs, or partial work remained.
Common causes - The command was only backgrounded in the current shell.
- The SSH or terminal session ended and took the job with it.
- The workload actually needed a persistent session or a service.
What not to do - Do not assume background means persistent.
- Do not restart the job the same way if the persistence model is still wrong.
- Do not turn one-off work into a permanent service without deciding if supervision is really needed.
Recovery steps - Decide whether the job should be rerun in a persistent session or under service supervision.
- Recreate the work only after the running model matches the real need.
- Verify how the chosen model behaves after disconnect or session end.
How to verify the fix - The work survives the event that used to stop it.
- You can reconnect or inspect the work in the intended way.
- You can explain why the new running model fits better.
Move on when - You can identify why the original run model failed.
- You can choose a safer persistence model.
- You can verify that the new model survives the expected session change.
Reflect before you leave - What made this job need persistence instead of simple backgrounding?
- Would a persistent session or a service have been the safer fit here, and why?
Review this troubleshooting path again in about 1, 7, 21 days.
Related learning M21 - Background and Foreground Understand how foreground work, background jobs, and persistent sessions differ so long-running commands do not surprise you or die unexpectedly.
M21A - Jobs, Sessions, and Services Understand when a background job is enough, when a persistent session is better, and when the operating system should supervise the work as a service.
M22A - Services, Supervision, and Restart Loops Connect services to process supervision so start failures, restart loops, and service health are easier to diagnose before you restart anything.