AWS Security ChangesHomeSearch

AWS codebuild: Add SSH troubleshooting for percent_expand and ControlPath errors

Service: codebuild · 2026-10-24 · Documentation medium

File: codebuild/latest/userguide/sandbox-troubleshooting.md · Type: network

Summary

Adds two troubleshooting sections for CodeBuild sandbox SSH failures: 'percent_expand: unknown key %n' (OpenSSH older than 8.1) and 'ControlPath too long' (hostname token %h in ControlPath), including guidance to set ControlPath to ~/.ssh/codebuild-sandbox-%C and to order the Host entry before Host *.

Security assessment

The change documents SSH client configuration for connecting to CodeBuild sandbox environments, including a ControlPath using the %C hash token instead of the full sandbox ARN hostname. This is security-adjacent local SSH config guidance (connection multiplexing socket paths) rather than a fix for a specific vulnerability, so medium severity.

Evidence

+        ControlPath ~/.ssh/codebuild-sandbox-%C

Diff

diff --git a/codebuild/latest/userguide/sandbox-troubleshooting.md b/codebuild/latest/userguide/sandbox-troubleshooting.md
index 3e4c915..b7d84ac 100644
--- a//codebuild/latest/userguide/sandbox-troubleshooting.md
+++ b//codebuild/latest/userguide/sandbox-troubleshooting.md
@@ -7 +7 @@
-StartSandboxConnection InvalidInputException error when SSH into CodeBuild sandbox environmentError: "Unable to locate credentials" when SSH into CodeBuild sandbox environmentStartSandboxConnection AccessDeniedException error when SSH into CodeBuild sandbox environmentError: "ssh: Could not resolve hostname" when SSH into CodeBuild sandbox environment
+StartSandboxConnection InvalidInputException error when SSH into CodeBuild sandbox environmentError: "Unable to locate credentials" when SSH into CodeBuild sandbox environmentStartSandboxConnection AccessDeniedException error when SSH into CodeBuild sandbox environmentError: "ssh: Could not resolve hostname" when SSH into CodeBuild sandbox environmentError: "percent_expand: unknown key %n" when SSH into CodeBuild sandbox environmentError: "ControlPath too long" when SSH into CodeBuild sandbox environment
@@ -22,0 +23,4 @@ Use the information in this topic to help you identify, diagnose, and address Co
+  * Error: "percent_expand: unknown key %n" when SSH into CodeBuild sandbox environment
+
+  * Error: "ControlPath too long" when SSH into CodeBuild sandbox environment
+
@@ -140,0 +145,59 @@ Use the information in this topic to help you identify, diagnose, and address Co
+## Error: "percent_expand: unknown key %n" when SSH into CodeBuild sandbox environment
+
+**Issue:** When attempting to connect to a CodeBuild sandbox environment using the command `ssh codebuild-sandbox-ssh=`<sandbox-arn>``, the command exits immediately, before any connection attempt, with the following error:
+    
+    
+    percent_expand: unknown key %n
+
+**Possible cause:** The OpenSSH client on your local machine is older than version 8.1. The SSH configuration that the CodeBuild sandbox connection script adds to `~/.ssh/config` uses the `%n` token in `ProxyCommand`. OpenSSH added support for this token in version 8.1.
+
+**Recommended solution:**
+
+  1. Run `ssh -V` to check the installed OpenSSH client version.
+
+  2. Upgrade the OpenSSH client to version 8.1 or later. On Amazon Linux 2, use an Amazon Linux 2023 host or install a newer OpenSSH client. If the setup script stopped with an OpenSSH version error, run the setup script again after the upgrade. A run that stopped at the version check did not change your configuration. If the setup script completed earlier, you do not need to run it again.
+
+  3. Retry your SSH connection to the sandbox environment.
+
+
+
+
+## Error: "ControlPath too long" when SSH into CodeBuild sandbox environment
+
+**Issue:** When attempting to connect to a CodeBuild sandbox environment using the command `ssh codebuild-sandbox-ssh=`<sandbox-arn>``, the command prints the following error and exits, where `<limit>` is 104 on macOS and 108 on Linux:
+    
+    
+    ControlPath too long ('<path>' >= <limit> bytes)
+
+**Possible cause:** Your `~/.ssh/config` sets a `ControlPath` for all hosts that includes the hostname token `%h`. The hostname of a CodeBuild sandbox is the full sandbox ARN, so the resulting socket path exceeds the operating system limit for Unix socket paths (104 bytes on macOS, 108 bytes on Linux).
+
+**Recommended solution:** The current CodeBuild sandbox SSH setup script adds a `ControlPath` that does not include the hostname to the `Host codebuild-sandbox-ssh*` entry. The script also places that entry before the other `Host` entries, because OpenSSH uses the first value it finds for each option. When you run the script again, it updates the existing entry and prompts you before it changes `~/.ssh/config`.
+
+  1. Download and run the CodeBuild sandbox SSH setup script again, as described in [Step 2: Modify local SSH configuration](./sandbox-ssh-tutorial.html#sandbox-ssh-tutorial.modify-ssh). Accept the change when prompted.
+
+  2. Retry your SSH connection to the sandbox environment.
+
+
+
+
+If you cannot run the setup script again, edit `~/.ssh/config` manually.
+
+  1. Open `~/.ssh/config` in a text editor.
+
+  2. Add a `ControlPath` line to the existing `Host codebuild-sandbox-ssh*` entry, as shown in the following example.
+    
+        Host codebuild-sandbox-ssh*
+        ControlPath ~/.ssh/codebuild-sandbox-%C
+
+`%C` is an OpenSSH token that expands to a short hash of the connection parameters.
+
+  3. Move the `Host codebuild-sandbox-ssh*` entry so that it comes before any `Host *` entry.
+
+
+
+
+To connect once without changing `~/.ssh/config`, pass the option on the command line:
+    
+    
+    ssh -o ControlPath=~/.ssh/codebuild-sandbox-%C codebuild-sandbox-ssh=<sandbox-arn>
+