Everything I learned debugging my first Box app

Writing your first Box app is sort of magical; in a couple of hours, you can go from having nothing to integrating with a bulletproof cloud filesystem.

Wondering how I did it?

Well, strap in because we're about to take a magical tour through the Box SDK and navigate through the ocean that is its first developer experience.

What we're trying to do?

I will show you how to overcome the most common issues with the Box Node.js SDK, when building something for the first time.

By the end of this article, you'll be a certified Box ninja, able to effortlessly chop, kick, and grab data from Box with Javascript.

The Box SDK provides a sweet wrapper around the Box API, making incorporating fancy file features into your node apps simple.

Like most beautiful things in life, however, there are some gotchas when getting started that you will learn by reading this article, and you will be glad that you did.

By the way, I used Dashcam - the best screen recorder for developers - to take video clips of the flow and bugs discussed below!

Issue #1: Misconfigured Authorization Callback

Problem:

When developing your Box app, after creating an Oauth2 authentication page, you might encounter an error saying Redirect URI mismatch, as shown below:

Solution:

To solve this, please ensure that you have configured the redirect URI on the Box Developer platform to match the one URL in your code. This is the URL within your application that will receive OAuth 2.0 credentials and can be configured within the configuration tab of your app here

Issue #2: Wrong token

Problem:

When trying to retrieve information (after successful authentication) with the Box API, I am hitting an error about the token being improperly formatted, as shown below.

Error occurred: AssertionError [ERR_ASSERTION]: tokenInfo is improperly formatted. Properties required: accessToken, refreshToken, accessTokenTTLMS and acquiredAtMS.

Solution:

This error is caused by your secrets data: CLIENT_ID, CLIENT_SECRET, SECRETKEY need to be defined as strings.

Double-check and ensure that your token is wrapped in quotes in your .env file to prevent this error!

Issue #3: Creating items - lack of permissions

Problem:

When you try to create a folder or a file with the Box API you might encounter an API response similar to the below one and the file/folder does not get created.

An error occurred Error: Unexpected API Response [403 Forbidden | .0a9157099d2d6c5f27336708e21f80f90]

Solution:

To recover from this error, provide a higher auth scope to your app by navigating to the developer console and ensuring the "Write all files and folders stored in Box" is selected. You can see the solution in the video embedded above. Do not forget to restart your app and re-authenticate!

Below, you can see how the same issue happens when trying to upload a file:

Issue #4: Issues with webhook

This is a fun one because it contains multiple levels of problems into one!

Problem A):

Using the Box API, you can modify files and folders and create a webhook that alert you when certain actions occur. You can create a webhook through the API, but sometimes you will face the following error when attempting to set it up

Unexpected API Response [403 Forbidden | .0738507f87ab4740283c35d3701e5d9ad]

Solution A)

Most likely, you haven't given your Box App the permission to create webhooks.

This setting differs from the ones that let you create files/folders.

See here:

Problem B)

When creating a webhook, even after having given your Box App the right permissions, you are facing a 400 error like the one below:

Unexpected API Response [400 Bad Request | nqr3b4hhsa30fy93.0a89df5b6bfbff030bc864b4d4c81e393] bad_request - Bad Request

Solution B)

The Box API requires you to create a webhook that uses SSL: The notification URL specified in the address parameter must be a valid URL starting with HTTPS

For example using Node.js

const result = await client.webhooks.create(
        '1303381221506', //my file id
        client.itemTypes.FILE,
        'https://some-endpoint-webhook.mydomain.com',
        [
            client.webhooks.triggerTypes.FILE.RENAMED,
            client.webhooks.triggerTypes.FILE.DOWNLOADED
        ])

Problem C)

When you create a webhook for a specific item, you cannot create a second webhook that is associated with it. You will otherwise face the following error.

Unexpected API Response [409 Conflict | 7ejx8thhsa6jg839.05e8c637b1ef2870c7ff9ae16cfddaac8] conflict - Bad Request

This means that we’re going to figure out another way…

Solution C)

The solution is to retrieve the existing webhook for this file/folder and then edit it. More information is available from this Github repository

You can also delete it first and then re-create it. There is no other way to modify an existing webhook at this moment.

By the way - here's a comprehensive list of actions the Box platform can send you a webhook for

Conclusion

This article showed you some of the most common issues and how to solve them with the support of video clips and error logs.

This should help you overcome these initial blocks to your developer experience when using the Box SDK for Node.js.

Getting started is pretty straightforward. The documentation is clear and has many examples- making it easy to get started. However if you face any issues, you can jump on the Box community forums and ask for help. Their developer relations team is constantly monitoring it and ready to help you get rolling with any technical, SDK or API question! Alternatively reach out to the unofficial community on Stackoverflow!