Everything I learned debugging my first Box Node.js 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, by overcoming beginner issues!
Strap in because we’re about to take a magical tour through the Box SDK and navigate through its first developer experience.
What are we 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 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 to take video clips of the flow and bugs discussed below so feel free to click through on the link to see the issues I faced like you were watching your favorite TV show on Netflix!
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 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 when using the SDK
😅 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 in Box — 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 webhooks
This is a fun one because it contains multiple levels of problems in one!
😅 Problem A:
Using the Box API, you can modify files and folders and create a webhook that alerts 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 RequestThis 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! 👋
If you liked this article and this interactive approach to writing developer content please let me know in the comments, or reach out on social media or via email!
