Introduction
Clarification: In this doc, an “error” can be a message that either the customer sees or one that you see in our tools while investigating. An example of an error a customer might see is the “unable to upload candidate” error in the Gem extension when pushing a candidate into Greenhouse. An example of an error you might see in Sentry is at the bottom of this doc.
On the Gem website and within our extension, we’ve got a few different errors that customers might run into, as well as problems that do not have a user-facing error, but generate one on our backend. Due to the complexity of our platform and integrations, the errors are often general and not very targeted when it comes to letting the customer know what to do in order to resolve it.
Fortunately, we do have tasks in our backlog to make error messaging more verbose and helpful. Until we get to an ideal state with each error message, each will require some investigation to figure out.
We can add specific examples of errors to this doc as we come across them for steps and best practices to triage, but will start with general best practices that should apply to most of the errors that you come across.
Debugging
- Understand what the customer was doing or was trying to do that led up to the error message. A step-by-step playback from them would be great, but you can also use FullStory to check.
- Assume the customer’s account and attempt to reproduce the issue, if possible.
- Use Chrome Console and/or Sentry to look up exceptions (errors) thrown by the customer’s user account. All exceptions that we are able to log for them will pop up in there. Make sure:
- The environment is set to Zensourcer
- The date range includes when the customer ran into the problem.
- That you use user.id=(insert ID here) to search for them.
- Ex. user.id:15199
- As a best practice, you should pull up your own Sentry logs and then bookmark the page for quick and easy access. That way, all you need to do is update the ID.
Chrome Console - Coming Soon
Sentry
If a customer runs into an error on the Gem website or extension, there will almost always be something logged in Sentry about it.
Most of the time, you will be able to see exceptions that are potentially related to your issue. For example, we are pretty good about showing “greenhouse” or “lever” within exception descriptions if they have to do with these integrations.
Common words to look for in Sentry, depending on your issue:
- Greenhouse
- Lever
- Gmail
- API
- Timeout
- Invalid
- Error
- Access
If we are lucky and the error description is verbose or clear in what the problem might be, you may be able to suggest specific troubleshooting steps to a customer.
Examples (add to this over time)
Google Reset Message History ID - Sequence stuck in Sending
<HttpError 404 when requesting https://www.googleapis.com/gmail/v1/users/me/history?historyTypes=messageAdded&maxResults=10&startHistoryId=775208&alt=json returned "Requested entity was not found.">Here is a common example of an exception that causes all of a customer’s sequences to get stuck in “sending”. In this case, Google has reset the user’s message history IDs, which causes them to not match with what we’ve got on our side. This breaks our email integration so all messages get stuck in the sending state: SEE HERE
Looking at the exception’s name, we see ERROR 404 and the URL includes “api” and “HistoryID”, which are the indicators for this problem.
For this issue, the resolution is to escalate the problem to Engineering and include the exception. They will fix the message history ID on our end and get the sequence(s) sent out to the candidates for the customer. (No action required on the customer’s side.)
Something fails to load
POST /api/graphql/batch: Timeout caught, attempting to grab stackAnother common exception is a timeout. What a customer might see in this case is a blank page or one that leads to some kind of error stating that the page has timed out or that they need to refresh it to try and get it to load.
In this particular example, a customer was trying to load a Prospects search query, but got notified that the page timed out: SEE HERE
The key word in this exception is TIMEOUT.
Depending on the severity of the issue (one-off vs consistent), you may need to escalate this to Engineering so they can have a look and see what might be causing it.