systemctl shows code=exited, status=217/USER
Main process exited, code=exited, status=217/USERShort 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.
Fix it fast
1Find out which cause you have
Show the unit as systemd reads it and look at the User= and Group= lines.
systemctl cat myapp.service2Match what you see, then jump to its fix
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 appuser2Fix
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=yes3Verify
Reload, restart and read the status.
sudo systemctl daemon-reload
sudo systemctl restart myapp.service
systemctl status myapp.serviceConfirmed by freedesktop.org
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 User2Fix
Use an account name that follows those rules, and update User= to match.
[Service]
User=appuser
Group=appuser3Verify
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
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 fixServers
Ansible hangs, then times out waiting for the sudo prompt
a playbook using become seems to hang
Ansible ran sudo on the target and never saw the answer it expected.
3 causes, each with a fixServers
Apache on Ubuntu returns 404 Not Found for my site
The requested URL was not found on this server.
On Ubuntu a 404 from Apache usually means the request maps to a path that has no file.
3 causes, each with a fixServers
Apache returns 504 Gateway Timeout when PHP takes too long
Quick requests work, slow ones end in a 504 after a fixed wait
A 504 from Apache means the backend did not answer within the proxy timeout.
2 causes, each with a fixServers
Apache logs SIGWINCH and exits on its own
the httpd container stops although nothing crashed
SIGWINCH is Apache's graceful-stop signal.
2 causes, each with a fixServers
Apache warns that a ${VAR} config variable is not defined
${VAR} left unchanged in the configuration, with a warning in the error log
Apache expands ${VAR} from Define or from the shell environment that exists when the server starts.
3 causes, each with a fix