Resolve username conflicts

Learn how to resolve UID conflicts between existing system users and Alpacon IAM users.

Cause of conflict

User conflicts occur due to UID (User ID) duplication:

  1. Existing user already on server before using Alpacon
  2. Alpamon agent installed and connected
  3. System user exists with same UID as IAM user (but different username)
  4. IAM user attempts to use websh, webftp, or deploy shell

If UID is already assigned to another user, the IAM user cannot use these features.

Identify conflict

Error message

When conflict occurs, you’ll see an error message:

User conflict detected: UID already in use

Server detail page

  1. Go to server detail page
  2. Select Access tab
  3. View conflicting users

Resolution

Alpacon intentionally does not auto-resolve conflicts to give you full control.

1. Check UID

Login to server and check current UIDs:

cat /etc/passwd

Output format: username:x:UID:GID:...

2. Choose resolution

Option 1: Delete existing user

Remove the existing user if no longer needed:

# Delete user only
sudo userdel <USER_NAME>
 
# Delete user and home directory
sudo userdel -r <USER_NAME>

Option 2: Change existing user’s UID

Keep existing user but change UID:

sudo usermod -u <NEW_UID> <USER_NAME>

Choose new UID that doesn’t conflict.

3. Sync agent

After changes, sync Alpamon agent:

sudo systemctl restart alpamon

Or from Alpacon web UI:

  1. Go to server list
  2. Select the server
  3. Run Agent Restart

Important notes

⚠️ Warning:

  • These operations may impact system behavior
  • Proceed with caution after confirming no side effects
  • AlpacaX is not responsible for issues caused by executing these commands

Recommendations:

  • Test on non-production server first
  • Create backup before changes
  • Verify related services work after changes

Prevent conflicts

Initial setup

Before registering server:

  • Check existing user UIDs
  • Plan to avoid overlap with Alpacon IAM user UIDs
  • Use high UID range if possible (e.g., 10000+)

UID policy

Establish UID assignment policy in workspace:

  • Use only specific UID range
  • Separate from existing system users

Troubleshooting

Conflict persists after changes:

  1. Verify agent restarted
  2. Check agent logs:
sudo journalctl -u alpamon -n 50
  1. Recheck Access tab in server detail

Services not working after change:

  1. Check file permissions owned by changed user
  2. Change file ownership if needed:
sudo find /path -user <OLD_UID> -exec chown <NEW_UID> {} \;