Identify And Resolve Errors With The Coveo Search API

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.