As described here https://aws.amazon.com/blogs/aws/new-amazon-ec2-feature-idempotent-instance-creation/ AWS CLI enforces idempotency of the aws ec2 run-instances --cli-input-json command. Unfortunately there is no documentation on how a client-token is generated.

I did find that there is a ClientToken field in the aws ec2 describe-instances results, but of course you still get the following error if you try to use one:

An error occurred (IdempotentParameterMismatch) when calling the RunInstances operation: Arguments on this idempotent request are inconsistent with arguments used in previous request(s).

How do I get a token to use with --client-token?

1 Answer 1


You make one up!

Putting any string < 64 chars will work. The describe call simply gives you back the client-token string used to create the instance

The idea then is then you handle failures like this.

  1. Generate the client Token i.e. "Bobs instance"
  2. Make successful run instance call with client-token
  3. Something goes wrong on the client i.e. Script fails or times out
  4. Your code starts again and generates the same client token( the trick is making sure this happens)
  5. You get an a success but you actually get back the same response with same reservation-Id you got the first time you made the request and no second instance is created

I suggest reading http://docs.aws.amazon.com/AWSEC2/latest/APIReference/Run_Instance_Idempotency.html for more info on idempotency.

It's been ages since I coded this but I believe when I did it I had my workers use the SQS message ID as the client-token, so if my workers failed, or sqs delivered twice, I wouldn't leak instances.

  • 1
    Thank you for taking the time to answer what must have seemed like a stupid question. It's funny that I tried every client token I could find in my logs and none of them worked... because they were in my logs as a result of having been used. The only string I tried that wasn't a logged client token was an aws sts get-session-token which failed because it was greater than 64 characters. Ugh! Dec 6, 2016 at 15:45
  • My new solution to this is aws ec2 run-instances --cli-input-json file://spec.json --client-token "$(TZ=UTC date)" which works great. However, I caution you not to do this in an unmonitored process. Idempotency is there for your protection. It's one thing to bypass it like this when you are mentally engaged at the CLI. Use caution doing so in automation. Dec 6, 2016 at 17:00
  • You can also just remove the --client-token parameter from the command, its optional.
    – Nath
    Dec 7, 2016 at 2:24
  • It's optional until it's required. It's required after you've run the command once. The requirement is there to prevent accidental rerunning of commands. When you are spinning up a cluster of Kubernetes servers, or something similar, it makes sense to want to launch 8 identical instances. But, you have to use --client-token to indicate you realize what you are doing. Dec 7, 2016 at 4:28

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .