FAQ & Troubleshooting

FAQ & Troubleshooting

---

Installation Issues

ssm-explorer: command not found after install

Your ~/.local/bin is likely not on your PATH. Add it:

export PATH="$HOME/.local/bin:$PATH"

Add this line to your ~/.bashrc or ~/.zshrc to make it permanent, then run source ~/.bashrc.

---

poetry: command not found

Install Poetry:

curl -sSL https://install.python-poetry.org | python3 -

See the official Poetry docs for more options.

---

AWS & Permissions Issues

AccessDeniedException on DescribeParameters

The default auto fetch strategy uses DescribeParameters, which requires additional IAM permissions. If your role doesn't have this, either:

1. Add ssm:DescribeParameters to your IAM policy, or
2. Force the path fetch strategy in your config:

[search]
fetch_strategy = "path"

The auto strategy should fall back automatically, but setting path explicitly avoids the extra API call.

---

My SecureString values show as *** (encrypted)

Pass --decrypt to any command that returns values:

ssm-explorer list /my/path --profile my_profile --decrypt
ssm-explorer get /my/path/MY_SECRET --profile my_profile --decrypt

Your IAM role must have kms:Decrypt permission for the KMS key used to encrypt the parameter.

---

NoCredentialsError or ProfileNotFound

• Check that your AWS credentials are configured: cat ~/.aws/credentials
• Check that the profile name you're passing exists: cat ~/.aws/config
• Run ssm-explorer check --profile YOUR_PROFILE to validate locally before hitting AWS

---

Config Issues

Where is my config file?

Default location:

~/.config/ssm-explorer/config.toml

Create it with:

ssm-explorer config init

---

My profile mapping isn't working

Make sure your config uses the correct TOML structure:

[aws.profiles.YOUR_PROFILE_NAME]
region = "eu-west-1"

Then verify with:

ssm-explorer check --profile YOUR_PROFILE_NAME

---

Output & Scripting

How do I use the output in a script?

Use --output json on list or search commands:

ssm-explorer list /my/path --profile my_profile --output json | jq '.[] | select(.name | contains("DATABASE"))'

---

How do I export all parameters to a .env file?

ssm-explorer export /my/path \
  --profile my_profile \
  --decrypt \
  --format env \
  --output-file .env

---

Reporting Issues

Please open an issue and include:

• Your OS and Python version (python3 --version)
• The command you ran (redact any sensitive paths/values)
• The full error output
• Output of ssm-explorer check