SessionManagerPlugin Is Not Found: Install It, Fix PATH

"SessionManagerPlugin is not found" means the AWS CLI cannot find the separate program it needs to open a Session Manager shell. Installing the AWS CLI does not install it. You put the Session Manager plugin on the machine where you type the command, reopen the terminal, and run session-manager-plugin to prove it answers. On Windows the installer is a plain SessionManagerPluginSetup.exe, not an MSI; on a Mac the signed package installs the program and then needs one symlink command that almost everyone skips; on Linux it is a .deb or an .rpm. If the error changes to TargetNotConnected after that, your laptop is done and the problem has moved to the instance.

Jake's phone repair shop has one EC2 instance that runs its booking page, and Ethan set it up the sensible way, with no SSH port open to the internet, because Session Manager gives you a shell without one. Which was fine until the evening Jake needed to restart something himself. The CLI he had just installed could list the instance, describe it, even stop it, and the one command he actually wanted, aws ssm start-session, gave him this error. His next move was going to be opening port 22 "just for tonight". Ethan asked him to put the security group down and spend two minutes on his own laptop first. This page is those two minutes, then the installer for each operating system, the PATH repairs for when the file is there and the shell still cannot see it, and the honest next step when the plugin works and the instance says it is not connected.

What the error is actually saying

The full text is usually SessionManagerPlugin is not found. Please refer to SessionManager Documentation here: http://docs.aws.amazon.com/console/systems-manager/session-manager-plugin-not-found. The important words are "not found". The CLI itself is fine, your credentials are fine, and the instance has not been consulted yet. The CLI simply went looking for a helper program on your computer and came back empty.

That helper is the Session Manager plugin, and it is a separate install because it does a separate job. Think of three pieces. The AWS CLI on your laptop asks Systems Manager to start a session. The plugin on your laptop is the client that actually carries the keystrokes back and forth once the session exists. And the SSM Agent on the instance is the other end of that conversation. All three have to be present, and the error on this page is only ever about the second one.

Here is why it feels so wrong. Almost every other AWS CLI command works without the plugin, because listing buckets or describing instances is just an API call. A successful EC2 listing proves your credentials, not your plugin. So "the AWS CLI works" and "I can start a session" are two different facts, and you can have the first for a year without ever having the second. The same plugin is also what aws ecs execute-command uses to open a shell inside a container, so an ECS Exec failure with this text has the same cure.

And the plugin lives where the command runs. On your laptop, if that is where you type. Inside the container, dev box or CI runner, if that is where the command runs. A plugin installed on your desktop does nothing for a script on a build server.

Jake: "The booking server shows green in EC2 and I still cannot get a shell. I was about to open port 22 to get in."

Ethan: "Leave the server alone for two minutes. The error is about your laptop, not the server, and the next six checks prove it one way or the other."

Two minutes before you install anything

Six commands, in order, and each one answers a single question. Most people find their answer at the second or fourth.

1. aws --version. If this fails, you have a CLI problem, and the plugin can wait.
2. session-manager-plugin. If it prints "The Session Manager plugin is installed successfully", the plugin is on this machine and visible to this shell.
3. session-manager-plugin --version. Write it down. You want 1.2.764.0 or later, and the current release is 1.2.835.0.
4. where.exe session-manager-plugin on Windows, command -v session-manager-plugin on macOS and Linux. This tells you where the shell found it, or that it did not.
5. If step 2 worked in this shell but the CLI still says not found, the command is running somewhere else: an IDE, a script, a container, a scheduled task with a different PATH. Compare that environment, not this one.
6. Only now, retry aws ssm start-session --target i-0123456789abcdef0 --region us-east-1 and read whatever new thing it says on its own terms.

The wrong turn almost everyone takes is to fix the AWS piece they know best. The table is kinder than instinct: find out who is actually complaining, and change only that layer. It matters most when the session command is buried in a script and the error you can see is three lines away from the one that caused it.

Versions that matter, and the ones that do not

Two version numbers matter on your side. The AWS CLI must be 1.16.12 or later, which every install from the last several years satisfies. The plugin's minimum supported version is 1.2.764.0, and AWS says operations on older versions may stop succeeding, so an old plugin that "worked last year" is a real suspect. The latest release, 1.2.835.0 from June 17, 2026, added SSH-style escape sequences to shell sessions and fixed port-forwarding sessions quietly dying after a WebSocket reconnect; the releases earlier in 2026 touched the Windows install script and where the SSM endpoint setting lives.

Two version numbers matter on the instance's side, and people mix them up with the plugin's constantly. Port forwarding to a port on the instance needs SSM Agent 2.3.672.0 or later; forwarding through the instance to another host needs 3.1.1374.0 or later. Those are agent versions on the server, a different number from the plugin on your laptop, and mixing the two up costs people an hour.

Keep both version strings in your notes. They are independent installs, and writing them down separately is the single habit that stops you reinstalling the wrong one.

Windows: the installer is an EXE, and the MSI you are searching for does not exist

Windows first, because it is where the search for an MSI sends people down a dead end. The real installer is a plain EXE, and it has been for years. It runs on 64-bit Windows 10 or later and Windows Server 2016 or later, it needs administrator rights, and it installs to %PROGRAMFILES%\Amazon\SessionManagerPlugin\bin\ if you leave the location box blank. AWS also says to use PowerShell 5 or later or the Command shell; third-party terminals may not behave.

1. Download https://s3.amazonaws.com/session-manager-downloads/plugin/latest/windows/SessionManagerPluginSetup.exe. A zipped copy exists at the same path as SessionManagerPlugin.zip; unzip it first, because extracting is not installing.
2. Run the EXE as administrator and accept the defaults.
3. Close every Command Prompt and PowerShell window, and any editor that owns a terminal. They keep the old PATH until they restart.
4. Open a fresh PowerShell window and run session-manager-plugin, then session-manager-plugin --version.
5. Retry your aws ssm start-session command.

If you would rather do it from PowerShell, download and launch with elevation in two lines.

Invoke-WebRequest -Uri "https://s3.amazonaws.com/session-manager-downloads/plugin/latest/windows/SessionManagerPluginSetup.exe" -OutFile "$env:TEMP\SessionManagerPluginSetup.exe"
Start-Process -FilePath "$env:TEMP\SessionManagerPluginSetup.exe" -Verb RunAs -Wait

That is interactive. MSI-only switches such as /qn will not work on it, so if your deployment system expects an MSI, check how it handles a plain EXE before you automate. When an update comes out, you run the installer again; there is no in-place updater. And if a new window still cannot find the command, AWS has a page for exactly that, and so does the PATH section below.

macOS: Homebrew, the signed package, and the line everybody skips

Jake: "I ran the Mac installer, it said it succeeded, and the command is still not found."

Ethan: "I believe you, because the installer is telling the truth and so is your shell. The package puts the program in one place and never tells the shell where to look. One line fixes it, and it is the line everybody skips."

There are three routes on a Mac. Homebrew is the easiest to maintain. The signed package is the native installer. The bundle is for when you want to choose where things go. Pick one; mixing them is how you end up with two copies and a shell that finds the old one.

Homebrew. One line, and the cask handles the link for you.

brew install --cask session-manager-plugin
session-manager-plugin --version

The signed package. Check your architecture with uname -m; arm64 means Apple silicon and the mac_arm64 path, x86_64 means the mac path. Then install, and then run the second line, which is the one AWS's own page lists and almost nobody runs.

# Apple silicon
curl "https://s3.amazonaws.com/session-manager-downloads/plugin/latest/mac_arm64/session-manager-plugin.pkg" -o "session-manager-plugin.pkg"
# Intel: use .../plugin/latest/mac/session-manager-plugin.pkg instead

sudo installer -pkg session-manager-plugin.pkg -target /
sudo ln -s /usr/local/sessionmanagerplugin/bin/session-manager-plugin /usr/local/bin/session-manager-plugin

The package installs the program under /usr/local/sessionmanagerplugin/bin. Your shell looks in /usr/local/bin. The ln -s line is the bridge between the two, and without it the installer can succeed and the command can be missing at the same time, which is exactly what Jake saw. If /usr/local/bin does not exist yet on a fresh Mac, create it, then run the link command again.

The bundle. Download sessionmanager-bundle.zip from the same mac or mac_arm64 folder, unzip it, and run its installer with an install directory and a link path. It needs Python 3.10 or later, and it will not install into a path with spaces in it.

unzip sessionmanager-bundle.zip
sudo ./sessionmanager-bundle/install -i /usr/local/sessionmanagerplugin -b /usr/local/bin/session-manager-plugin

Whichever route you took, open a new terminal and prove it: command -v session-manager-plugin should print a path, and session-manager-plugin --version should print a number. If the signed package installed the binary but command -v finds nothing, the link line was skipped. Make the link, after checking it will not overwrite a Homebrew-managed one. To remove the bundle install later, delete /usr/local/sessionmanagerplugin and the link in /usr/local/bin.

Ubuntu and Debian: the matching .deb

Debian and Ubuntu use a .deb, and the only decision is the architecture. Run uname -m before you copy a command; x86_64 wants the ubuntu_64bit package and aarch64 wants ubuntu_arm64. It does not matter whether the machine is a laptop, a cloud VM or a container.

# x86_64
curl "https://s3.amazonaws.com/session-manager-downloads/plugin/latest/ubuntu_64bit/session-manager-plugin.deb" -o "session-manager-plugin.deb"
# ARM64: use .../plugin/latest/ubuntu_arm64/session-manager-plugin.deb instead

sudo dpkg -i session-manager-plugin.deb
session-manager-plugin --version

If dpkg complains about the architecture, you downloaded the other package; the message is telling you the truth, and running it again changes nothing. dpkg -L session-manager-plugin lists the files the package put down, which is the fastest way to see where the executable went when the package says it installed and the shell says it cannot find it. To remove it, sudo dpkg -r session-manager-plugin.

This package is not amazon-ssm-agent, and the agent does not stand in for it. A Linux machine that opens sessions needs the plugin, a machine that receives them needs the agent, and a machine that does both needs both.

Amazon Linux and RHEL: yum or dnf with the .rpm URL

The RPM distributions take the package straight from the URL. Amazon Linux 2 and RHEL 7 use yum; Amazon Linux 2023 and RHEL 8 or 9 use dnf. Pick the architecture folder the same way as above.

# Amazon Linux 2 or RHEL 7, x86_64
sudo yum install -y https://s3.amazonaws.com/session-manager-downloads/plugin/latest/linux_64bit/session-manager-plugin.rpm

# Amazon Linux 2023 or RHEL 8 and 9, x86_64
sudo dnf install -y https://s3.amazonaws.com/session-manager-downloads/plugin/latest/linux_64bit/session-manager-plugin.rpm

# ARM64 on either: replace linux_64bit with linux_arm64

Then session-manager-plugin --version, and rpm -ql session-manager-plugin if you want to see the files. Removal is sudo yum erase session-manager-plugin -y. If your organization checks package signatures, AWS publishes a verification procedure; it is worth the five minutes before you roll the package to a fleet.

One scenario worth naming: an EC2 instance that opens sessions to other instances is a client and needs the plugin, while still needing the agent to be managed itself. Installing one does not give you the other.

The file is there and the shell cannot see it

If you have installed the plugin twice and it still says not found, you are not going mad. The file is there. Your shell, or the program that launched the command, simply is not looking in that folder. PATH is the list of folders a shell searches for commands, and the plugin can be perfectly installed and still invisible to one particular process, because an IDE, a scheduler, a container or a child process can each carry a different PATH from the one in your terminal.

Windows. First prove the file exists, then prove the bare command fails, which separates "not installed" from "not on the PATH".

Test-Path "C:\Program Files\Amazon\SessionManagerPlugin\bin\session-manager-plugin.exe"
& "C:\Program Files\Amazon\SessionManagerPlugin\bin\session-manager-plugin.exe"
where.exe session-manager-plugin

If the full path runs and the bare name does not, add the folder to your PATH the way AWS describes: press the Windows key, type environment variables, choose Edit environment variables for your account, select PATH, choose Edit, and add C:\Program Files\Amazon\SessionManagerPlugin\bin\ after a semicolon. Then close every command window and reopen. For a quick test in the current window only, $env:Path += ";C:\Program Files\Amazon\SessionManagerPlugin\bin" works until you close it.

macOS. command -v session-manager-plugin, ls -l /usr/local/bin/session-manager-plugin and type -a session-manager-plugin between them tell you whether the link exists, where it points, and whether a second copy is being found first. With the signed package or the bundle, the program is under /usr/local/sessionmanagerplugin/bin and the link is in /usr/local/bin. With Homebrew, look in the Homebrew prefix instead of overwriting a working Homebrew link.

Linux. command -v session-manager-plugin and echo "$PATH", then dpkg -L or rpm -ql to see where the package really put the executable. If the package lists it and the shell cannot find it, the folder is not on the PATH. If the package does not list an executable at all, the symlink guessing can wait; check whether the install really completed first. And before any privileged recursive delete of an old installation, find out which package manager owns those files, because that command does not ask twice.

Proving it, and proving which account you are in

The bare session-manager-plugin command should answer "The Session Manager plugin is installed successfully. Use the AWS CLI to start a session." That proves the executable is reachable from this shell. It proves nothing about the instance, your credentials or your permissions, so the next two lines are the ones that matter before you point a session at a production server.

aws sts get-caller-identity
aws configure list
aws ssm start-session --target i-0123456789abcdef0 --region us-east-1 --profile production

Read the account ID that comes back. A working profile that belongs to a different account is a surprisingly common reason for an instance that "does not exist", and a Region mismatch between your dev scripts and your production ones is the other. Once the plugin runs, a new error is a new clue, not a relapse: AccessDeniedException points at your permissions, and TargetNotConnected points at the instance or at the wrong account and Region.

TargetNotConnected: the laptop is done, the instance is next

Jake: "Good news, the plugin runs. Bad news, now it says TargetNotConnected."

Ethan: "That is good news twice. The laptop is done. Everything from here is about the instance, and the instance only needs four things."

The message reads An error occurred (TargetNotConnected) when calling the StartSession operation: i-0123456789abcdef0 isn't connected. AWS gives two explanations, and they cover almost every case: the instance is not fully set up for Session Manager, or you are asking for an instance that lives in a different account or Region than the one your CLI is pointed at. Check the cheap one first.

1. aws sts get-caller-identity --profile production. Is this the account the instance is in?
2. aws ec2 describe-instances --instance-ids i-0123456789abcdef0 --region us-east-1 --profile production. Does the instance exist here, and is it running?
3. aws ssm describe-instance-information --region us-east-1 --profile production. Is the instance in Systems Manager's list at all, and does it show as online?
4. If it is missing from that list, work through the agent, the permissions and the network, in the next three sections, in that order.

EC2 saying "running" and Systems Manager saying "online" are two different things. A virtual machine can be up while its agent is stopped, its role is missing, or it has no path to the service. That gap is the whole of the next three sections, and the full version of it, with the endpoint rules for newer Regions, is in the SSM Agent post linked below.

Is the SSM Agent running on the instance?

The agent is the software on the instance that answers Systems Manager. If it is not installed, or not running, there is nothing for your session to connect to. On Amazon Linux and RHEL it is a systemd service; on Ubuntu images that ship it as a snap, the service has a different name; on Windows Server it is a Windows service you check from an administrative PowerShell on the server, not on your laptop.

# Amazon Linux, RHEL
sudo systemctl status amazon-ssm-agent
sudo systemctl enable --now amazon-ssm-agent

# Ubuntu (snap)
sudo snap services amazon-ssm-agent
sudo snap start amazon-ssm-agent

# Windows Server (on the server)
Get-Service AmazonSSMAgent
Start-Service AmazonSSMAgent

If there is no service, install the agent for that operating system; some images, Red Hat's among them, do not ship it. If it starts and then drops offline again, read its log, because "service running" and "node connected" sound like the same thing, and they are not. An agent can be running with no permission to register or no route to the service, and it will say so in its own log.

The awkward case is the instance built deliberately without SSH, where the only way in was the session you cannot open. Start with the control-plane checks you can do from outside: the account and Region, the attached role, the managed-node list, the VPC endpoints. If your environment has an approved out-of-band path, use it. The honest answer is that fixing a broken agent on a sealed instance sometimes needs the person with infrastructure permissions rather than the person who normally opens sessions, and a one-line diagnosis like "the agent cannot reach ssmmessages from this subnet" is what gets them moving.

Two permission checks, not one

There are two separate permission questions, and granting more on one side never fixes the other. Your identity must be allowed to start a session, which is the ssm:StartSession action on the target. And the instance must be allowed to talk to Systems Manager, which is an IAM role attached as an instance profile, usually carrying the AmazonSSMManagedInstanceCore policy.

aws ec2 describe-iam-instance-profile-associations --region us-east-1
aws ec2 associate-iam-instance-profile --instance-id i-0123456789abcdef0 --iam-instance-profile Name=ApprovedSSMProfile --region us-east-1

If the instance has no profile and an approved one exists, an authorized person can attach it with the second command. Resist creating a broad new role just to clear the warning. And if a profile is already attached, you cannot add a second one; review the existing association and change it through the proper process. There is also a newer way for an account to manage instances without attaching a profile to each one, Default Host Management Configuration, which has its own prerequisites on the instance side, including a recent SSM Agent. So a missing profile is not automatically a mistake in an account that uses it; find out which model your organization chose.

If you see AccessDeniedException on your side, start with aws sts get-caller-identity, then look at your ssm:StartSession permission, any resource restrictions on it, permission boundaries and organization policies. An explicit deny somewhere up the chain cannot be out-voted by a broader allow.

The path to ssm and ssmmessages

The instance has to reach Systems Manager over HTTPS, and the two endpoints that matter most are ssm.REGION.amazonaws.com and ssmmessages.REGION.amazonaws.com. It can get there through outbound internet access or through interface VPC endpoints. In a private subnet, check the endpoint network interfaces, their security groups, private DNS, the VPC's DNS settings, and the instance's route table. A VPC endpoint existing somewhere in the VPC is not the same as being reachable from this subnet with a policy that allows this use.

From a Windows client you can at least prove the service port answers: Test-NetConnection ssmmessages.us-east-1.amazonaws.com -Port 443. A successful TCP test is narrower than a session, though; it does not check permissions, registration or the full protocol, and it tests your laptop's network, not the instance's. Do the equivalent test from the instance's own network context when you can.

Opening SSH port 22 or RDP port 3389 to the internet because Session Manager is down trades one afternoon's problem for a permanent one. The whole point of Session Manager is administrative access with no inbound ports. Fix its prerequisites and keep the advantage.

A worked port-forwarding example: a private web app on port 8080

Suppose a service on the instance listens on port 8080 and you want it on your laptop as localhost:18080. The ports are illustrative; what matters is that the service is actually listening on the instance. The document is AWS-StartPortForwardingSession, and the quoting differs by shell.

# macOS and Linux
aws ssm start-session --target i-0123456789abcdef0 \
  --document-name AWS-StartPortForwardingSession \
  --parameters '{"portNumber":["8080"],"localPortNumber":["18080"]}' --region us-east-1

# Windows Command Prompt
aws ssm start-session --target i-0123456789abcdef0 ^
  --document-name AWS-StartPortForwardingSession ^
  --parameters portNumber="8080",localPortNumber="18080" --region us-east-1

Keep that terminal open and visit http://localhost:18080. If the page does not load, the tunnel is probably fine and the application is not listening, or your local port is already taken. On Windows, Get-NetTCPConnection shows what is listening locally; if 18080 is busy, change the local port to 18081 and leave the remote one alone, because the application on the instance did not move.

To reach something beyond the instance, a database on a private address for example, the document is AWS-StartPortForwardingSessionToRemoteHost with a host parameter, and the instance needs SSM Agent 3.1.1374.0 or later. The tunnel gets you to the database port; the database still asks for its own password, and a login error at that point is the database's business, not the session's.

Jake: "So the tunnel can be perfect and the page can still be broken."

Ethan: "Right. The tunnel is a corridor. If the room at the end is empty, the corridor did its job."

Six things that look like a bad plugin and are not

Every CLI command works except start-session. That is the normal shape of this error, not a contradiction. Listing buckets needs credentials and an API; a session needs the plugin and a ready instance on top. If the plugin answers in your terminal but a script still says not found, capture the PATH inside the script, because a script does not inherit the environment you see at the prompt.

A new terminal finds it, a scheduled job does not. Services, CI runners and scheduled tasks run under their own account and environment. A PATH you fixed for your user is not the service's PATH. Diagnose inside the job, and make the plugin part of how that runner is provisioned, so a rebuilt runner tomorrow does not depend on someone having clicked an installer today.

The instance was replaced, or lives in another Region. A well-formed instance ID can still be stale after an autoscaling event, or copied from an inventory for a different Region or account. Use explicit --region and --profile while investigating, and confirm the ID in the EC2 console for that account before chasing agent logs.

The session document is rejected. InvalidDocument with "Document type: 'Command' is not supported. Only type: 'Session' is supported" means the --document-name you passed is a Run Command document, not a Session document. The Systems Manager console lists Session documents under their own category. A malformed request is fixed in the request, never in the target IAM role.

The shell opens and shows nothing. A blank screen is a different problem from a missing plugin; by then the session exists. AWS lists a full root volume on the instance, a console link with mismatched Region and endpoint, session logging pointed at an S3 bucket or log group the VPC endpoints cannot reach, or a deleted log destination. Change one thing at a time; if you reinstall the plugin, edit IAM, change a route and reboot all at once, a working result teaches you nothing.

Port forwarding freezes after it worked. Antivirus software can deadlock the plugin during port forwarding; AWS's fix is to exclude the plugin's install path from the scanner, with your security team's blessing. The June 17, 2026 release also fixed port-forwarding sessions dying after a reconnect, so upgrade before you spend an afternoon on it.

When it runs in Terminal and fails in VS Code

An integrated terminal inherits its environment from the editor that owns it. A new terminal tab inside the same window still inherits the old environment, so the restart has to be the whole application. The same is true of a Node or Python script that launches the CLI: if the script gives the CLI an absolute path but a PATH without the plugin folder, the CLI finds itself and not its helper. Fix the environment the child process receives, rather than reinstalling the package a fourth time.

Several copies on disk are the other quiet cause. type -a session-manager-plugin on Unix shells and where.exe session-manager-plugin on Windows show the order the shell searches, which is how a freshly installed 1.2.835.0 can appear to do nothing while an old copy answers first. Work out which install belongs to Homebrew, dpkg, RPM or the native installer before you remove any of them.

And the browser console working while the CLI does not is a clue, not a contradiction. The console route has none of your laptop's requirements, so a successful console session tells you the instance side is healthy and the fault is in your plugin, your profile or your environment.

What to collect before you ask for help

When the obvious fixes have failed, write down enough that the next person does not have to repeat the whole investigation. One sentence describing the earliest failure that still happens, the exact command without any secrets, the operating system and architecture, how the plugin was installed, aws --version and session-manager-plugin --version, the profile and Region, whether a direct-path launch of the plugin works, whether the browser console can start a session to the same instance, and whether the failure is before the session is created, during startup, or after a tunnel opens.

Leave out access keys, SSO tokens and session credentials. Then route it: a workstation that cannot see its own executable is a workstation problem, a policy denial belongs to whoever owns the policy, and an instance with no route to the service belongs to the network or platform team. "The agent cannot reach ssmmessages from this subnet" moves a ticket; "Session Manager is broken" does not.

Jake's evening ended well. The plugin went on his laptop, the symlink went in, the first session opened, and the security group that was about to get port 22 stayed exactly as Ethan had left it. The server was never the problem. It usually is not.

Questions people ask about the Session Manager plugin

If a session has stopped you in the middle of real work, keep the three pieces apart in your head: your laptop, your identity, and the instance. The error on this page lives entirely on the first one, and it is the cheapest of the three to fix. Once the plugin answers, do not start over; take whatever the next message says at face value and follow it to the instance. Jake's server never needed port 22, and yours probably does not either.

Revision note. Written October 8, 2026, against plugin version 1.2.835.0 and the 1.2.764.0 minimum. If you have just cleared the missing-plugin message and met TargetNotConnected instead, that is progress: keep the local fix and follow the instance.