Identify And Resolve Errors With The Coveo Search API

Using Coveo Headless's QueryError Component

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>Something broke! {state.error!.message}</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.

👋 Hey Sitecore Enthusiasts!

Sign up to our bi-weekly newsletter for a bite-sized curation of valuable insight from the Sitecore community.

What’s in it for you?

  • Stay up-to-date with the latest Sitecore news
  • New to Sitecore? Learn tips and tricks to help you navigate this powerful tool
  • Sitecore pro? Expand your skill set and discover troubleshooting tips
  • Browse open careers and opportunities
  • Get a chance to be featured in upcoming editions
  • Learn our secret handshake
  • And more!
Sitecore Snack a newsletter by Fishtank Consulting

Meet 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.

Connect with David