Identify And Resolve Errors With The Coveo Search API

Using Coveo Headless's QueryError Component

September 17, 2022

By David Austin

Easily Debug Your Search Problems

Getting to the source of the issue when using Coveo Headless can sometimes be a pain. Thankfully Coveo Headless has a relatively simple way for you to get to the root of the problem.

It's called the Headless QueryError component and it's been around for more than a few versions now. And while it can provide you an easily readible Json formatted response as to what may be happening within the Search API. It's likely something you'd only want enabled while in development or QA. Unlikely you'd want this thing popping up while in Production.

We've added this to a recent NextJs app we've built as a way to debug some Search API calls we were finding weren't giving us the results we were expecting.

The Code

import { useEffect, useState } from 'react';
import { QueryError as HeadlessQueryError } from '@coveo/headless';
import { QueryError as HeadlessQueryError, buildQueryError, SearchEngine } from '@coveo/headless';
import HeadlessEngineContext from './HeadlessEngineContext';

const QueryError = (): JSX.Element => { const engine = useContext(HeadlessEngineContext) as unknown as SearchEngine; const controller = buildQueryError(engine) as HeadlessQueryError; const [state, setState] = useState(controller.state);

useEffect(() => controller.subscribe(() => setState(controller.state)), []);

if (!state.hasError) { return <></>; }

return ( <div> <div>Something broke! {state.error!.message}</div> <code>{JSON.stringify(state.error)}</code> </div> ); };

export default QueryError;

You could pass the controller into the component. Here we've used the buildQueryError using the engine context we built here.

The HeadlessQueryError controller has both an error detection (hasError) but also returns the error message itself, state.error, that you can then display in human readible Json format. It's updated each time a Search Api event is triggered.

Add this component to your search page, maybe even make it such that it only shows up with a certain query parameter present (i.e. your own version of debug) or whatever criteria you want. And now you can more readily identify problems and solve them before your visitors discover them unwittingly.

Image of Fishtank employee David Austin

David Austin

Development Team Lead | Sitecore Technology MVP x 3

David is a decorated Development Team Lead with Sitecore Technology MVP and Coveo MVP awards, as well as Sitecore CDP & Personalize Certified. He's worked in IT for 25 years; everything ranging from Developer to Business Analyst to Group Lead helping manage everything from Intranet and Internet sites to facility management and application support. David is a dedicated family man who loves to spend time with his girls. He's also an avid photographer and loves to explore new places.