Maximum length of application environmental variables

Hey team Balena,

Your docs on environment and service variable doesn’t mention the maximum length of environment or service variables. I need to add an allow list feature and spend very little time doing it.

Is there a maximum char limit on the value side? Can I get away with variables in the low thousands?

There doesn’t seem to be a problem in my testing up to a couple hundred at least but I wanted to be sure before I push this to my sometimes connectivity challenged fleet.


Hey @tacLog, besides the maximum length, the byte size of the string is also a consideration. Low thousands of characters or less than 1MB shouldn’t be a problem. I could say that with confidence.

Then I don’t know the exact limit and I asked internally. I also opened this issue to document this:

Thank you for the ask. We’ll give an update to clarify the exact limit.



While we currently rely on the (generous) database limits only, consider the fact that such variables are fetched on each poll that doesn’t return 304 and, as a result, can significantly increase your traffic usage.
If you’re storing some labels or metadata, you may consider tags for that purpose.

Hey @gelbal

Thanks for the update, it sounds like my use case of a couple hundred characters will be fine. I look forward to seeing what kind of limit you guys apply and always appreciate being able to follow issues in git.


While I am by no means new to balena OS or the balena engine, I am afraid your answer goes out of the depth of my knowledge.

I tired to answer my own questions with docs and this forum but would like you to confirm I got it right if that’s possible.

What is a poll?
I am assuming it is state update requested by the supervisor on the device from the balena backend.
How often does a poll occure by default?
I think this might be controlled by: “BALENA_SUPERVISOR_POLL_INTERVAL” which appears to default to 90000 ms so 15 minutes.

I couldn’t answer these:
When would a 304 return?
Would the polling interval of 15 minutes apply to when a 304 returns or would it try again sooner?
Is the polling interval of my entire fleet going to be in sync if there is a mass power cycle on location?

Thank you for your time,

As @pranasziaukas suggested using tags.

Which I could use because my devices already set and get their tags to report back statistics of how they are doing at their purpose.

Would it be better for this allow list of several hundred characters to be a tag?

It makes it slightly more difficult on my end because I have to handle getting the tag and failing to get the tag via the api. As my devices have to support full functionality in offline mode, I then also have to handle caching a allow list to the local file system, and deciding when to invalidate that cache.

However, unless I am misunderstanding things the benefit of putting this allow list in a tag is that the state poll from the supervisor won’t pull the list every 15 minutes and the only way the device will only pull the list when it requests the tag from the api.

Are their any other benefits? Because for my current list length of a couple hundred characters, I am still planning on doing this the easy way with an application variable that will always be present if set.


Hello @tacLog ,

That’s correct, at each BALENA_SUPERVISOR_POLL_INTERVAL the device will check if there were any changes (more info here and here) and retrieve the potentially big env var, which can cause significant bandwitdh use.

When a 304 is returned, it means that there were no changes (environment variables, releases, etc.), so in that case, the env vars would not be retrieved.

The device checks (and retrieves if something changed) for changes on every boot. So if there’s a mass power-cycle, all those devices will potentially re-download the env vars.

Hope this makes things a bit clearer but do let us know if you have any other questions.