systemctl failed: how to discover why a Linux service won't start

Published on 2026-10-26 by frfrand

Debugging systemd services with status, journalctl and permissions

You deploy, the panel says the build finished and your domain returns 502. Many times the problem is one level below: the service running the API never started or crashed right away.

I'll show you where the problem is, how to check it without guessing, and what I would do in an application that really has users. You don't need to memorize an entire manual to fix a specific failure.

What systemctl failed means in practice

systemd supervises services and exposes their status via systemctl. A failed service can be due to a wrong path, permissions, environment variables, occupied port, or an exception in the code. The status does not always reveal the cause: that's what logs are for.

A clarification before touching the server: if the project is already in production, save the state you found and check on which user and machine you are going to run the commands. Working as root without need and changing several things at once makes it difficult to find the cause of an error.

Useful commands to start

sudo systemctl status miapp --no-pager
sudo journalctl -u miapp -n 80 --no-pager
sudo systemctl cat miapp
sudo ss -ltnp
# Tras corregir un archivo .service
sudo systemctl daemon-reload
sudo systemctl restart miapp

Paths, unit names, and domains are examples. Adapt them to your service. If a command requires administrator permissions, check what changes and why. Diagnostic queries should come before modifications.

Step by step, with checks

1. Check the exact unit with systemctl status.
2. Read the logs around the last execution and locate the first specific error.
3. Review ExecStart, WorkingDirectory, User and the variables file, without printing secrets.
4. If you changed the unit, run daemon-reload before restarting.
5. Verify local port and /health path before looking at the domain again.

After each step, verify an observable result: a status, a file, an HTTP response or a log entry. If you find an unexpected message, save it to investigate instead of hiding it with repeated restarts.

Real example: an application that needs to be maintained

Django was working before updating dependencies. Upon restarting, Gunicorn fails because the virtual environment path changed. The log says No such file or directory; adding more RAM would not fix anything.

Finally, test the full path: enter through the domain, call the API, write a test data and verify that the information is still there after a controlled restart. A server that "starts" is not always an application that works.

Errors worth avoiding

Restarting constantly without reading logs can hide the failure and cause more outages. If the error comes from a data migration, reinstalling the service will not solve the incompatibility.

It is also important that credentials do not end up in terminal history, logs, shared files, or screenshots. For users and services, use minimal permissions and document who can revoke access.

How ArduMaker fits into this scenario

ArduMaker makes it easier to observe and manage services within the VPS; note the unit and deployed commit to correlate a 502 with the change that caused it.

ArduMaker can help you manage VPSs, deploy repositories, and work with services, databases, and domains from the same platform. It does not replace what we just explained about Linux: precisely for that reason, it is worth understanding the diagnosis and having a way to repeat it.

When it is worth automating it

If the task is repeated, document the manual procedure and its checks first. Then consider a script or a scheduled task with visible errors, logs, and limited permissions. Do not automate a command that you do not yet know how to recover when it goes wrong.

Frequently asked questions

Can I test it without affecting customers? In many cases, yes: a staging VPS or a separate test service allows you to validate the configuration before changing production.

How do I know it went well? Check logs and a functional operation, not just that the command ended with a zero code.

When do I need more resources? When metrics indicate CPU, RAM, disk, or connection saturation. A configuration failure is rarely fixed by hiring more memory.

References

• Official tool documentation
• Related ArduMaker article
• ArduMaker resources

In one sentence: first understand the error, then change one concrete thing and check its effect. That discipline saves you many hours of support.