Error/Warning Glossary

[EchoReaper]

Errors and warnings are helpful for developers who are familiar with an API and how it works, but not for anyone who’s not particularly experienced with it. Developers who are trying out an API for the first time, are new to the platform/programming entirely, or just haven’t explored enough of a feature to know its quirks don’t really benefit enough from error/warning messages.

For example, this warning was obvious to me because I have used DataStores extensively in the past, but others could not identify the problem. We should have an error/warning glossary on the dev hub that explains what each means. For example, instead of:

DataStore request was added to the queue. If request queue fills, further requests will be dropped. Try sending fewer requests.

the error glossary entry could look something like:

DataStore request queue full

Warning text: “DataStore request was added to the queue. If request queue fills, further requests will be dropped. Try sending fewer requests.”

Explanation:

All DataStores used in your game share a pool of requests that they are allowed to send. When one DataStore makes a request with Get/SetAsync/etc, it decrements this pool by 1. This pool is automatically incremented over time, but if requests are sent more quickly than it replenishes and the pool reaches 0, any further DataStore requests will not be processed.

To make it easier on developers, Roblox will queue a certain amount of requests past this threshold and wait for until there are more requests available in the pool and then send the DataStore request. However, this queue has a fixed size to prevent buildup of thousands of requests – if requests continue to be made, the queue will fill up and further requests from all DataStores will error. This warning signifies this point – cut back on the amount of requests you’re sending, or bad things will happen.

Common Causes:

Saving to DataStores on the Changed event
Problem: The .Changed event may fire very rapidly depending on the instance it’s hooked up to, surpassing the amount of available requests
Solution: Instead of saving on .Changed, save every 5 minutes, when the player leaves, and when the server closes

Accessing DataStores on a RemoteEvent/Function
Problem: Players may use exploited clients to fire the remote objects more than you intended, eating up your requests
Solution: Check if the RemoteEvent/Function is being fired too often (ignore the request if so), or change so requests are not tied to the Remove objects (e.g. save or pull every 5 minutes)

Accessing DataStores on player input
Problem: You load data every time a player clicks a button (e.g. next page on leaderboards), but the player can spam-click the button as often as they like, draining the amount of available requests
Solution: Rate-limit how often players can pull from DataStores, and if possible, cache the data server-side so if Player1 has already loaded Page4, Player2 can receive Page4 from the server instead of asking DataStores

Accessing too fast
Problem: You, as the developer, are using requests faster than the request pool replenishes
Solution: Make sure you are abiding by DataStore rate limits, cache data, and combine requests to the same key when you can

The problem with the current documentation is that when a developer encounters an error, we’re pretty much asking them to read a whole article (or more) on the subject, and hope they have enough of an understanding of how the feature works to determine what the error message means. It would help out developers a lot if we explicitly described why each error happened, common causes, and solutions to those causes. We don’t have to ship the whole list at once – it can be gradually built over time.

[EndorsedModel]

This would be awesome to have as a resource that I can point devs to who need help debugging their code instead of having to rely on someone else to translate what their errors mean in practical application. I know it can take a while for scripting to click with some people but I’ve noticed that even basic errors can confuse new scripters and I think something like this could be immensely useful to them. Even for me, when dealing with areas I haven’t dealt with before it would be nice to know what some of the errors I may get mean.