Node.js Error Handling

Node.js Error Handling – ERR_ARG_NOT_ITERABLE

Making our way through our in-depth Node.js Error Handling series, today we’ll be going over the first of the various System Errors that can be thrown in Node, ERR_ARG_NOT_ITERABLE. Node throws a System Error when an exception occurs within the program’s runtime environment and are typically an indication that there was an operational problem within the application. In the case of the ERR_ARG_NOT_ITERABLE error, the its appearance indicates that a Node.js API method or function expected an iterable argument, but the actual value passed was not an iterable.

Within this article we’ll examine the ERR_ARG_NOT_ITERABLE system error in greater detail by first looking at where it resides in the overall Node.js Error Class Hierarchy. We’ll also examine some functional code samples that illustrate how a typical Node.js API class (URLSearchParams) might throw an ERR_ARG_NOT_ITERABLE if passed arguments are the incorrect type. Let’s get into it!

The Technical Rundown

Most Node.js errors inherit from the Error base class, or extend from an inherited class therein. The full error hierarchy of this error is:

Full Code Sample

Below is the full code sample we’ll be using in this article. It can be copied and pasted if you’d like to play with the code yourself and see how everything works.

When Should You Use It?

The ERR_ARG_NOT_ITERABLE code indicates that an iterable argument was expected within a particular Node.js API method call, but a non-iterable object type was passed instead. At present, there are not many Node.js API methods that throw ERR_ARG_NOT_ITERABLEs, so we’ll just be taking a look at a single example class that does this, the URLSearchParams constructor. The primary purpose of URLSearchParams is to provide read/write access to the query string values of a URL. It can easily parse, append, or otherwise modify parameters, to simplify the process of handling URLs and URIs.

To illustrate the use of URLSearchParams we start with a simple test method that wraps the URLSearchParams constructor and passes the provided parameter to it, before logging and returning the result:

With this function ready to go we can perform a series of simple tests by passing various types of values to see how the URLSearchParams constructor handles them. We’ll begin with a simple string that most of us are accustomed to seeing in our browsers:

Executing this code produces the following output:

The --- STRING TEST --- header indicates the type of argument value that was passed, and below that we see the produced URLSearchParams object that resulted. Everything works as expected!

We’ll next try passing an object:

This works just as before, producing a value instance and output:

The URLSearchParams constructor can also accept iterable objects, such as arrays or Map objects:

As before, both of these tests work as expected and produce valid outputs:

Modern JavaScript includes the ability to create iterators and generators. An iterator is basically a function that knows how to provide access to a sequential set of items. There are a number of ways to create an iterator, but ECMAScript 2015 introduced the Symbol.iterator well-known symbol, which is used to define an object’s default iterator method. Once an iterator function is defined for an object, that object can then be used in iterable situations, such as the common for...of loop.

In the following example we try to pass a set of params to URLSearchParams that uses the Symbol.iterator to define an iterator function as an array:

Running this code finally throws a TypeError with the explicit ERR_ARG_NOT_ITERABLE code attribute, indicating that the query pairs of the iterator must be iterable:

This particular error might not make much sense, but it becomes much clearer if we look at the internal url.js:111 source code that threw the error in the first place:

The URLSearchParams constructor accepts object and function type arguments. It then generates a local method variable to retrieve the @@iterator method of the passed init parameter using inti[Symbol.iterator]. In our example code case, this iterator isn’t equivalent to this[Symbol.iterator], but method is also not a function, so it throws an ERR_ARG_NOT_ITERABLE TypeError.

To resolve this issue we merely need to actually assign an iterable function to the Symbol.iterator value in the params object:

Here we’re using the function* declaration, which defines a generator function that can use the special yield keyword to iterate through returned values. In this case, we’re yielding key/value pairs for the query params we want to create. Executing this well-formed iterable function test works as expected and produces the following output:

Airbrake’s robust error monitoring software provides real-time error monitoring and automatic error reporting for all your development projects. Airbrake’s state of the art web dashboard ensures you receive round-the-clock status updates on your application’s health and error rates. No matter what you’re working on, Airbrake easily integrates with all the most popular languages and frameworks. Plus, Airbrake makes it easy to customize error parameters, while giving you complete control of the active error filter system, so you only gather the errors that matter most.

Check out Airbrake’s error monitoring software today and see for yourself why so many of the world’s best engineering teams use Airbrake to revolutionize their exception handling practices!