Os erros da AWS CLI parecem todos iguais pra quem está começando — um bloco em inglês com um nome entre parênteses. Mas o nome entre parênteses é o diagnóstico: ele diz se o problema é achar a credencial, a credencial em si, a permissão ou o comando. Abaixo, os que mais aparecem, com a mensagem como ela sai no terminal (tirada da CLI versão 2 e da documentação oficial de solução de problemas), o que ela quer dizer e o que fazer.
aws configure list # que perfil, que chave, que região — e de onde veio cada um aws sts get-caller-identity # com que conta e identidade a AWS acha que está falando
A maioria dos "não funciona" é a CLI usando uma credencial ou uma região
diferente da que você imagina — uma variável de ambiente esquecida, um perfil sem
--profile. Esses dois comandos mostram isso em segundos. Se ainda
assim não fizer sentido, rode o comando que falhou com --debug: ele
mostra onde a credencial foi encontrada, o pedido enviado e a resposta crua.
aws: [ERROR]: An error occurred (NoCredentials): Unable to locate credentials. You can configure credentials by running "aws login".
O que quer dizer: A CLI procurou uma credencial em todos os lugares onde ela olha (variáveis de ambiente, ~/.aws/credentials, SSO, role da máquina) e não achou nenhuma. Não é problema de permissão: a AWS nem chegou a ser chamada.
Como resolver: Configure uma credencial: aws configure (chave de acesso), aws login (sua sessão do Console) ou aws sso login --profile x (SSO da empresa). Se você usa perfil com nome, lembre do --profile — sem ele a CLI procura o default.
aws: [ERROR]: An error occurred (NoRegion): You must specify a region. You can also configure your region by running "aws configure".
O que quer dizer: A credencial existe, mas nem o comando nem o perfil dizem a região — e quase todo serviço da AWS é regional.
Como resolver: Grave uma região no perfil (aws configure set region sa-east-1) ou passe --region no comando. A ordem de prioridade é: --region, variável AWS_REGION, variável AWS_DEFAULT_REGION e, por último, o region do perfil.
aws: [ERROR]: The config profile (dev) could not be found
O que quer dizer: O --profile (ou a variável AWS_PROFILE) aponta pra um perfil que não existe no ~/.aws/config — geralmente erro de digitação, ou o perfil existe noutro computador.
Como resolver: Liste os perfis com aws configure list-profiles e use um deles, ou crie o que falta com aws configure --profile dev.
An error occurred (AccessDenied) when calling the AssumeRole operation: User: arn:aws:iam::123456789012:user/ana is not authorized to perform: sts:AssumeRole on resource: arn:aws:iam::123456789012:role/admin
O que quer dizer: Aqui a credencial funcionou: a AWS sabe quem você é e respondeu que essa identidade não tem permissão pra essa ação. A mensagem diz as três coisas que importam — quem (User:), qual ação e em qual recurso.
Como resolver: Confira primeiro se a identidade é a que você imagina (aws sts get-caller-identity) — metade dos casos é perfil errado. Se for a certa, falta uma política que permita exatamente aquela ação naquele recurso. Comandos como aws s3 sync chamam várias APIs; o --debug mostra quais.
An error occurred (InvalidClientTokenId) when calling the GetCallerIdentity operation: The security token included in the request is invalid.
O que quer dizer: A chave de acesso configurada não existe mais (ou foi desativada). No S3 a mesma situação aparece como InvalidAccessKeyId: "The AWS Access Key Id you provided does not exist in our records". O caso clássico é depois de uma rotação de chave: a nova foi criada, a velha desativada, e um perfil ficou com a velha.
Como resolver: Veja qual chave o perfil usa (aws configure list --profile x mostra os 4 últimos caracteres) e compare com aws iam list-access-keys. Atualize com aws configure set aws_access_key_id ... e aws_secret_access_key. Confira também se não há AWS_ACCESS_KEY_ID antiga numa variável de ambiente — ela vence o arquivo.
An error occurred (SignatureDoesNotMatch) when calling the ListBuckets operation: The request signature we calculated does not match the signature you provided. Check your key and signing method.
O que quer dizer: Toda chamada é assinada com o seu segredo e com a hora do seu computador. Se o segredo está errado (copiado pela metade, com espaço, com caractere especial mastigado por algum script) ou se o relógio da máquina está vários minutos fora, a assinatura não bate.
Como resolver: Confira o relógio (date) — em máquina virtual que hibernou é comum ele ficar pra trás. Se a hora está certa, gere o segredo de novo: a AWS não mostra o segredo antigo outra vez.
An error occurred (ExpiredToken) when calling the ... operation
O que quer dizer: Credencial temporária (de assume-role, SSO ou aws login) tem prazo. Passou do Expiration, toda chamada falha — mesmo que tenha funcionado há uma hora.
Como resolver: Renove: aws sso login --profile x no SSO; um novo assume-role se você copiou as credenciais à mão. Melhor ainda: perfil com role_arn + source_profile, que renova sozinho.
aws: [ERROR]: An error occurred (ParamValidation): argument subcommand: Found invalid choice 'copy' ... aws: [ERROR]: Unknown options: --regiao, x
O que quer dizer: O comando ou a opção não existe — ou existe numa versão da CLI mais nova que a sua. A CLI lança versão quase todo dia útil, e serviço novo só aparece depois de atualizar.
Como resolver: Confira a grafia no manual (aws s3 help lista os comandos do serviço). Se está certa e a documentação mostra o comando, atualize a CLI — veja Como instalar a AWS CLI.
command not found: aws
O que quer dizer: O sistema não acha o programa: instalação incompleta, terminal aberto antes da instalação, ou pasta de instalação fora do PATH.
Como resolver: Feche e abra o terminal; confira com which aws (Linux/Mac) ou where aws (Windows); se não aparecer, a pasta precisa entrar no PATH.
(a saída aparece no less; é preciso apertar q pra voltar ao terminal)
O que quer dizer: A versão 2 manda respostas longas pro paginador do sistema. Em script, isso trava a execução esperando uma tecla.
Como resolver: Use --no-cli-pager no comando, ou defina cli_pager = (vazio) no perfil, ou a variável AWS_PAGER="".
[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed
O que quer dizer: Quase sempre é rede de empresa com proxy que abre o HTTPS com um certificado próprio, que a CLI não conhece.
Como resolver: Aponte a CLI pro certificado da empresa (.pem) com --ca-bundle, com ca_bundle no perfil ou com a variável AWS_CA_BUNDLE. Desligar a verificação de SSL resolve o sintoma e abre um buraco — não faça.
O formato é sempre An error occurred (Código) when calling the
Operação operation: mensagem. A operação diz qual API
falhou — útil quando um comando chama várias, como o s3 sync. O
código é o que você pesquisa. Erro sem esse formato, começando com
aws: [ERROR]: e sem "when calling", aconteceu antes de sair da
sua máquina: é configuração local, não permissão na AWS.
Veja também: Comandos básicos da AWS CLI e a lição Configurar a AWS CLI (perfis, credenciais, SSO e assume-role).
O jeito mais rápido de reconhecer esses erros é provocar cada um num lugar seguro. A trilha grátis Configurar a CLI do CLImb faz exatamente isso: você erra o perfil, fica sem região, rotaciona a chave e vê o token inválido — e conserta — num terminal simulado, sem conta na AWS.
Praticar no terminal