The requested historical offset (X) is beyond the historical buffer’s limit (Y)

In Pine Script^®, a single script executes from start to end on each bar of the chart. After each execution on a confirmed bar, Pine’s runtime system commits (saves) data for a script’s variables and expressions on that bar to fixed-sized historical buffers. The script can retrieve past bar values from these buffers by using the [] history-referencing operator or the functions that reference history internally. For example, the expression myVar[500] retrieves the last saved value of the myVar variable as of 500 bars back.

By default, the runtime system automatically sizes a script’s buffers to store only what the script requires for the historical references that it performs across historical bars:

• The system first checks the historical references that the script executes on the first 244 bars of the dataset, then sets an initial buffer size based on those references. If the script uses constant historical offsets, or if the historical offsets used on subsequent bars do not exceed the buffer sizes, the script’s historical references work without issues.
• If the script requests data from beyond an initial buffer’s limit while executing across other historical bars, the system increases that buffer’s size and restarts the script. This process repeats as necessary until the system reaches the restart limit or the script loads successfully without exceeding a buffer’s boundaries.

This runtime error can occur in some rare cases if the system fails to determine the appropriate size of a buffer on historical bars after restarting a script several times. However, the error more commonly occurs when a script executes out-of-bounds historical references on realtime bars, because the system does not continue to resize historical buffers after the script loads.

For example, the following script plots the value of close variable from 500 bars back on historical bars, then attempts to plot the value from 1000 bars back on realtime bars. The script initially loads successfully across the chart’s history. However, the script halts and raises the runtime error once a new realtime tick becomes available. The error is also reproducible by enabling Bar Replay and pressing “Forward” once. The automatic historical buffer for the close series in this example contains only 500 past values. It does not contain 1000, because the script does not reference values from 1000 bars back on any historical bars, and the system does not resize the buffer on realtime bars. Consequently, the historical offset of 1000 on the first realtime bar is beyond the historical buffer’s limit:

To resolve such errors, programmers must ensure that their scripts’ historical buffers have a sufficient size to accommodate historical references on all bars. See below to learn more.

Potential fixes

The following sections explain the different ways to explicitly define appropriate buffer sizes to accommodate historical references. Using these techniques is necessary only if a script’s historical references cause this runtime error. In most other cases, we typically recommend relying on automatic buffer sizing.

Use the ​max_bars_back()​ function

The built-in max_bars_back() function explicitly sets the initial size of the historical buffer for a specified variable. If automatic buffer sizing fails, or if a script references deeper history on only realtime bars, programmers can use this function to specify appropriate buffers for specific series to accommodate historical references for up to 5000 bars back.

For example, to resolve the error in our initial script above, we can add the call max_bars_back(close, 1000) to specify that the buffer for the close series stores at least the latest 1000 past values. With the appropriate buffer size explicitly defined, the script performs its historical references successfully on realtime bars without raising an error:

Note that:

• Scripts can include a max_bars_back() function call at any location in the script. In our example above, the call occurs after the historical reference on the close variable.

Use the ​max_bars_back​ parameter

The max_bars_back parameter of the indicator() and strategy() functions is an alternative to max_bars_back() that defines the initial size of all series in a script if it has a specified argument. This parameter can offer convenience in cases where multiple series require manually defined buffers. However, it’s crucial to understand that increasing the size of every historical buffer in a script can negatively impact its runtime performance and memory consumption. Therefore, for resource efficiency, we typically recommend using the max_bars_back() function to size only specific buffers instead of sizing every buffer with this parameter. The only exception is if all or most of the series in the script actually require historical buffers with a specific size and the runtime system fails to determine that size automatically.

Use the larger historical reference on early bars

An alternative way to increase the size of a specific historical buffer is to use the largest required offset in historical references on early bars, regardless of whether the script requires that offset on those bars. The runtime system analyzes that historical offset while the script loads and sets the buffer’s size accordingly.

For example, the script version below includes the offset of 1000 in the history-referencing operation on the first bar, where the barstate.isfirst value is true. This change makes no practical difference in the historical output, because the operation returns na for any nonzero offset on the first bar. However, it resolves the error because it causes the script to request data for 1000 bars back on a historical bar, forcing the system to create a buffer that maintains the latest 1000 past close values:

Historical buffer errors in realtime drawings

A common cause of the historical offset error is the creation of drawing objects that anchor to the past while the script executes on realtime bars. All Pine drawings that rely on chart coordinates convert their x-coordinates into timestamps by referencing the time series internally, even if the programmer defines those coordinates using bar_index values.

Therefore, if a script draws into the past on realtime bars and raises this error, the typical solution is to set an explicit buffer size for the time variable.

For example, the script below draws a horizontal line from the bar at bar_index - 500 to the current bar while executing on realtime bars only. The script loads successfully across historical bars, but it quickly halts and raises the historical offset error on the first realtime tick. Although the script does not explicitly use the [] operator, the line drawing itself references the time series internally to convert its x1 and x2 coordinates. Converting the x1 coordinate to a timestamp requires access to the time value from 500 bars back. However, the default buffer for that series stores fewer than 500 past values, because the script does not request the value from 500 bars back while it loads across the historical dataset:

To resolve the error, programmers must use any of the techniques described in the Potential fixes section to explicitly set the size of the historical buffer for the time series. The simplest solution is to use the max_bars_back() function to set the appropriate buffer size.

In the script version below, we added the call max_bars_back(time, 500) to specify that the buffer for the time series stores values for the latest 500 past bars. This change prevents the script from requesting a value that is outside the buffer’s boundaries when converting the bar_index - 500 coordinate into a timestamp: