ssh to agent can fail with uuid error

Last updated: June 25, 2026

SSH Connection Error: "user must be an existing uuid or username" When Agent Name is "coder"

Symptoms

When attempting to SSH into a workspace using the command shown in the Coder UI, you encounter the following error:

Encountered an error running "coder ssh", see "coder ssh --help" for more information
error: "user" must be an existing uuid or username.
queried user="coder"

The UI displays a command like:

ssh coder.$workspace-name.$USER.coder

However, removing the agent name from the command makes it work:

ssh $workspace-name.coder

Cause

This issue occurs when the agent is named "coder" in your template. The SSH configuration generated by coder config-ssh uses patterns like coder.* and *.coder for hostname matching. When the agent name is also "coder", this creates a conflict in parsing the SSH command.

Part of this behaviour may become deprecated (the coder.* part)! Stay tuned.

The .ssh/config file accepts:

  • coder.* - Commands starting with "coder."
  • *.coder - Commands ending with ".coder"

However, it cannot properly parse coder.*.$USER.coder (e.g., coder.$workspace-name.$USER.coder), which is what the UI displays when your agent is named "coder".

Affected Versions

This issue has been confirmed in Coder v2.26.2.

Workaround

Use one of the following working formats:

  1. Remove the agent name from the command:

    ssh $workspace-name.coder

  2. Use the workspace name only:

    coder ssh $workspace-name

  3. Use the full format with agent prefix (for non-"coder" agents):

    ssh coder.$workspace-name.$USER.coder

    Note: This only works when the agent name is NOT "coder".

Resolution

Recommended: Rename your agent to something other than "coder" (e.g., "main", "primary", or "default") in your template configuration to avoid the naming conflict. Alternatively, document internally the best method to access, and especially the output of coder config-ssh as the authoritative method!

Example agent configuration in your template:

resource "coder_agent" "main" {
  # ... agent configuration
}

After updating the agent name in your template:

  1. Update the template: coder template push
  2. Update existing workspaces to use the new template version
  3. Re-run: coder config-ssh

Investigation Status

This behavior has been identified as a potential bug where the UI displays an SSH command format that is incompatible with the .ssh/config configuration when the agent is named "coder". The discrepancy between what coder config-ssh generates and what the UI displays is being investigated by the engineering team.

Additional Information

If you continue to experience issues after trying these workarounds, please provide the following information to Coder support:

  • Your Coder server and CLI version
  • Contents of your .ssh/config file (the CODER section)
  • Your template configuration (particularly the agent definition)
  • The exact SSH command you're attempting to use