What's the deal with GreenGrass Components and Semver?

Question

I was messing around trying to automate development-builds of a GG component, and I continuously hit weird behaviors with the way GGv2 handles semver.

1. I tried putting the date as the patch version, eg: `1.2.20250602121212` and this failed, presumably because of an integer overflow on the patch part being too large of a number.
2. I tried putting a regular old post-fix version eg `1.2.3-dev1` and this worked in publishing the component to the aws console, but failed when downloading to the device.
3. I got an error saying dev versions should start with a letter and not a number, so I tried the version `dev-1` and then it wouldn't let me publish the version to the gg component registry.

It seems like different rules or validations are applying at different places, and the error messaging around it is not very helpful.

Please update the GG docs, error-handling, etc. to make this a bit easier :D

What is the recommended way to version pre-release development builds?

aws_fz · Answer

Thank you for reaching out. Please adhere to the standard semantic versioning format. For our system, the maximum allowed value for each component (major, minor, and patch) is 999999.
Will bring this up with the team to ensure our documentation is updated accordingly.

re:Post Agent · Answer

In AWS IoT Greengrass V2, component versioning follows specific rules that can be confusing when trying to automate development builds.

The issues you encountered highlight the constraints of Greengrass component versioning:

1. For version numbers like `1.2.20250602121212`, you likely hit an integer overflow because the patch number was too large. Greengrass expects semantic versioning with reasonable integer values.

2. With `1.2.3-dev1`, you were able to publish to the console but encountered download issues because Greengrass has different validation rules at different stages of the component lifecycle.

3. For `dev-1`, this format doesn't follow the required semantic versioning pattern that Greengrass expects.

The recommended approach for versioning pre-release development builds in Greengrass V2 is to:

1. Use standard semantic versioning (major.minor.patch) with reasonable integer values
2. Increment the version number for each new deployment, even if the code hasn't changed
3. For development builds, consider using a sequential numbering approach with small integers, such as incrementing the patch version (e.g., 1.0.1, 1.0.2, etc.)

When you need to force a component restart without code changes, you can:
- Increment the component version
- Update the component's environment variables using the `Setenv` configuration in the recipe
- Use the Greengrass CLI to restart components during development (not recommended for production)

These approaches provide reliable ways to manage component versions while avoiding the validation issues you encountered.  
**Sources**  
[How do I redeploy the same deployment config in Greengrass v2 | AWS re:Post](https://repost.aws/questions/QUzpTAgObZSbaHNbJgxkiXyQ/how-do-i-redeploy-the-same-deployment-config-in-greengrass-v2)  
[Deploy AWS IoT Greengrass components to devices - AWS IoT Greengrass](https://docs.aws.amazon.com/greengrass/v2/developerguide/manage-deployments.html)  
[Troubleshooting AWS IoT Greengrass V2 - AWS IoT Greengrass](https://docs.aws.amazon.com/greengrass/v2/developerguide/troubleshooting.html)

What's the deal with GreenGrass Components and Semver?

Add your answer

Relevant content