Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

systemctl shows code=exited, status=217/USER

ErrorMain process exited, code=exited, status=217/USER

Short answer

Exit status 217/USER means systemd could not find or switch to the account named in User= before starting the program. The program never ran. Either the account does not exist on this machine, or the name is not valid. Fix the unit's User= line or create the account, then reload.

  • Applies to systemd 255, Ubuntu 24.04, Amazon Linux 2023
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Show the unit as systemd reads it and look at the User= and Group= lines.

    systemctl cat myapp.service
  2. 2Match what you see, then jump to its fix

    1. 1status=217/USER right after a deploy to a new server or a fresh imageThe account in User= does not exist on this machineFix
    2. 2The account seems to exist but 217 persists, and the name is long or has unusual charactersThe user name breaks systemd's naming rulesFix

What does the error look like?

  • Main process exited, code=exited, status=217/USER

Cause 1 of 2

The account in User= does not exist on this machine

1Check

Without DynamicUser=, the user must already exist in the user database when the service starts, or the program fails to start. Ask the system whether it knows the name.

grep -E '^(User|Group)=' /etc/systemd/system/myapp.service
getent passwd appuser

2Fix

Create the account first, or point User= at one that exists. For a simple service that needs no fixed account, let systemd allocate one.

[Service]
DynamicUser=yes

3Verify

Reload, restart and read the status.

sudo systemctl daemon-reload
sudo systemctl restart myapp.service
systemctl status myapp.service

Confirmed by freedesktop.org

Did this fix it?

Cause 2 of 2

The user name breaks systemd's naming rules

1Check

systemd expects letters, digits, underscore and hyphen only, not starting with a digit or hyphen, and 1 to 31 characters long.

getent passwd | cut -d: -f1 | awk 'length($0) > 31'
systemctl show myapp.service -p User

2Fix

Use an account name that follows those rules, and update User= to match.

[Service]
User=appuser
Group=appuser

3Verify

Reload and restart, then confirm the process runs as that user.

sudo systemctl daemon-reload
sudo systemctl restart myapp.service
ps -o user= -p "$(systemctl show -p MainPID --value myapp.service)"

Confirmed by freedesktop.org

Did this fix it?

How do I stop it coming back?

  • Create service accounts in the same provisioning step that installs the unit file.
  • Read the unit back with systemctl cat on the target machine before you start it.
  • Prefer DynamicUser=yes for services that only need a state directory.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Related fixes

Servers

dnf cannot install MySQL on Amazon Linux 2023

dnf cannot find a mysql-server package on Amazon Linux 2023

Amazon Linux 2023 documents MariaDB, not MySQL, as its database server, with packages named mariadb105 and mariadb105-server.

3 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.