Troubleshooting

Manually configuring your shell profile

If you keep your shell profile in a non-standard location, Granted may fail to install the alias. If this happens, you can manually add the alias to your shell profile. Some examples are included below to assist you:

Bash

Add the following to ~/.bash_profile:

alias assume="source assume"

ZSH

Add the following to ~/.zshenv:

alias assume="source assume"

Fish

Add the following to ~/.config/fish/config.fish:

alias assume="source /usr/local/bin/assume.fish"

AWS SSO issues

Regions

Entering the wrong sso_region will result in this cryptic looking error:

Invalid SSO Region Error

If you don’t know which SSO region your AWS organization is in, you’ll need to check with whoever set up your AWS SSO service. Alternatively, you can just guess until you get it right. There’s only twenty-one of them.

UnauthorizedException: Session token not found or invalid

If you receive the following error when running assume:

[✘] operation error SSO: GetRoleCredentials, https response error StatusCode: 401, RequestID: 39287367-65d6-41bc-a01f-ebc34b65e5b4, UnauthorizedException: Session token not found or invalid

Run the following steps to resolve the issue:

Clear the AWS SSO plaintext token cache:

rm -rf ~/.aws/sso/cache

After completing this step, retry running assume. If assume still fails, continue below.

Clear the Granted CLI cache:

granted cache clear

If you are using MacOS, open Keychain Access and remove any entries starting with granted in the login keychain.
Run the Granted credential-process command and inspect the output:

granted credential-process --profile=<name of AWS profile you want to access>

If you receive an error such as the following:

[✘] error when retrieving credentials from custom process. please login using 'granted sso login --sso-start-url https://example.awsapps.com/start --sso-region us-east-1'

Run the corresponding Granted command to reauthenticate.

If you are still running into issues with assume and AWS SSO, you can use the --no-cache or set the GRANTED_NO_CACHE environment variable to true, which forces a refresh of AWS session tokens.

assume --no-cache

# also configurable via the GRANTED_NO_CACHE environment variable
export GRANTED_NO_CACHE=true

If you are using the Granted Credential Process integration, you can opt out of session token caching for a particular AWS command as follows:

# 'aws sts get-caller-identity' is an example AWS command
GRANTED_NO_CACHE=true aws sts get-caller-identity --profile example-profile-using-granted-credential-process

Where does Granted store its settings?

Granted settings are in ~/.granted. If your trying to find where a setting is coming from, also check these directories:

~/.aws
~/.password-store
~/.gnupg
~/.local/share/keyrings

gpg: decryption failed: no secret key

If you are trying to use pass, make sure you followed the instructions. Note that export GPG_TTY=$(tty) must have been executed in the current shell so that you can be asked for your password.

Granted stopped working (Windows)

On Windows in WSL2, Granted can sometimes stop working completely. The solution is to reboot.

Other issues

If you have any other issues with Granted please send us a message on Slack and we’ll help you out. Alternatively, you can also shoot us a Twitter message.

Please don’t hesitate to reach out! We want to make Granted work for everyone and we’re keen to help you with any problems you might encounter.

Browser extension: troubleshooting native messaging

The browser extension uses Native Messaging to communicate with the Granted CLI, for purposes such as checking the user confirmation code matches during an AWS IAM Identity Center sign-in.

For native messaging to work, the browser reads a JSON manifest file. This file is created automatically by Granted.

If this file is not present in the correct location for your browser, you may see an error message like the following:

Error: specified native messaging host not found.

To troubleshoot this error, you can create this file manually. The contents of the file should be:

{
   "name":"io.commonfate.granted",
   "description":"Granted BrowserSupport",
   "path":"/opt/homebrew/Cellar/granted/0.35.0/bin/granted",
   "type":"stdio",
   "allowed_origins":[
      "chrome-extension://cjjieeldgoohbkifkogalkmfpddeafcm/"
   ]
}

Replace the path field in the file with the path to Granted on your system. You can determine this by running which granted on MacOS and Linux.

Follow the guide in the Chrome documentation to place the file in the correct location based on your operating system.