I see 'Pine cannot determine the referencing length of a series. Try using max_bars_back' error

//@version=4
study("Drawing max_bars_back")
// max_bars_back(time, 5000)
var int pastBar = na
if barstate.islastconfirmedhistory
    pastBar := bar_index - 300
if barstate.islast
    label.new(pastBar, 1, text = "Label text")

When a Pine script is calculated, it creates a historical buffer of a certain size for each variable or function in the code. That buffer contains information about previous values of the variable/function and is used when the code refers to the past values using the [] history-referencing operator. The size of the buffer specifies how far into the history this value can be requested. 

Pine automatically determines the required buffer size for all variables and functions by analyzing past references made while calculating the script on the first 244 bars. If no past references are detected, a default buffer size is assigned to the variable or function. For variables, the default buffer size is 300 bars, for functions it is one bar. 

In some cases, Pine is not able to assign a proper buffer size for that function and the default buffer size is used instead. This can happen: 

  • In branches of conditional statements (if, iff, or ?) when past references to a variable or function inside the conditional statement are first executed when the 244th bar has already passed.
  • In functions that support dynamic length, when the length value passed to the function after the 244th bar is greater than any value that was passed to it before (when the buffer was being calculated).

Take a look at the code below. It will return the aforementioned error because:

  • The var1 variable value is not known at the time of compilation
  • The test variable does not request any past data on the first 244 bars of the chart

Due to this, the test variable gets assigned a default buffer of 300 bars. When the script requests the value of the 301st bar in the past, which is outside of the variable's buffer, an error occurs. 

//@version=4
study("max_bars_back var", overlay=true)
var1 = input(301)
test = 0.0
//max_bars_back(test, 301)
if bar_index > 244
    test := test[var1]
plot(test)

The max_bars_back parameter and the max_bars_back() function exist to work around this. They allow you to specify the correct buffer size for variables and functions when the default buffer doesn’t suffice. Uncomment the max_bars_back() function call in the code above. A buffer of 301 will be assigned to the test variable and as a result, the script will calculate properly.

Here is an example of a function call to which the default one-bar buffer size is attributed because it is not invoked in the first 244 bars. While no explicit reference to past values using the [] operator is used, the function nonetheless requires the past 20 values to calculate. The script will thus return the max_bars_back error:

//@version=4
study("Requires max_bars_back")
test = 0.0
if bar_index > 1000
    test := vwma(close, 20)
plot(test)

 The max_bars_back() function cannot be used to assign a specific buffer size to a function. When you need to do so, or when you want to set the default buffer size for all variables and functions in a script, add the max_bars_back parameter to the script’s study or strategy declaration statement. Note that using the parameter will increase the script's resource usage, so this method should only be used when needed:

//@version=4
study("Requires max_bars_back", max_bars_back=20)
test = 0.0
if bar_index > 1000
    test := vwma(close, 20)
plot(test)

You may also resolve the issue by taking the problematic expression out of the conditional branch, in which case the max_bars_back parameter is not required:

//@version=4
study("Requires max_bars_back")
test = 0.0
vwma20 = vwma(close, 20)
if bar_index > 1000
    test := vwma20
plot(test)

The error may also arise when using functions allowing dynamic lengths, i.e., series values. The following script will throw the max_bars_back error because during the first 300 bars, sma() is calculated with a length of 50, and thus only requested 50 bars of historical data, limiting its buffer to 50. After the 300th bar, however, the length changed to 100, which is out of bounds of its established buffer:

//@version=4
study("Out of bounds")
series_length = bar_index > 300 ? 100 : 50
plot(sma(close, series_length))

To work around this issue, you can generate a larger buffer in the beginning of the indicator’s calculations by using an intentionally large length value. In the following code, we request 1000 bars of historical data on the first bar of our indicator’s calculations. This creates a permanent 1000-bar buffer for our sma(), and as a result we never go out of bounds:

//@version=4
study("Not out of bounds")
series_length = bar_index > 300 ? 100 : 50
passed_length = bar_index == 0 ? 1000 : series_length 
plot(sma(close, passed_length))

Another case where this error may appear is when the script uses drawings that are placed on the chart based on the bar_index variable. The built-in variable bar_index uses the time series in its inner workings. Before a drawing is displayed on the chart, its coordinates are converted from bar_index to UNIX time. Accessing the value of the bar index X bars back requires the history buffer size of the time series to be of size X or more. This value is automatically detected based on how the script is calculated on the historical data. If after getting to the real-time calculation the script refers to a bar_index beyond than time series buffer, it cannot be converted to UNIX time, which will cause the error to appear. 

The script below demonstrates this behavior: initially, it will compile and calculate properly, but as soon as a new bar appears, it will return a runtime error. When the script is applied on the chart, it first saves the bar_index of a bar 300 bars before the last one to the pastBar variable. The value kept in that variable is then used as an X-coordinate to draw a label on. This causes the script to create a 300-value buffer for the time series. As soon as a new bar appears, that same index now refers to a bar 301 bars before the last one. The time series buffer is only 300, so the bar_index can no longer be converted, which causes the error to appear.

To work around this issue, you can use the max_bars_back() function to create a buffer for the time series. Uncomment the function in the code below to see the fix in action:

//@version=4
study("Drawing max_bars_back")
//max_bars_back(time, 5000)
var int pastBar = na
if barstate.islastconfirmedhistory
    pastBar := bar_index - 300
if barstate.islast
    label.new(pastBar, 1, text = "Label text")

You can learn more about max_bars_back and the related error in our User Manual.