Skip to content

Improve GraphQL and backend connectivity error messaging in frontend #4421

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
hassaansaleem28 wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Improve GraphQL and backend connectivity error messaging in frontend #4421

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
4795497
fix: improve graphql error messages
hassaansaleem28 Mar 29, 2026
2bf6efb
Merge branch 'main' into fix/improve-onboarding-graphql-error
hassaansaleem28 Mar 31, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 6 additions & 2 deletions frontend/src/app/global-error.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -62,7 +62,11 @@ export class AppError extends Error {
}
}

export const handleAppError = (error: unknown) => {
interface HandleAppErrorOptions {
timeout?: number
}

export const handleAppError = (error: unknown, options?: HandleAppErrorOptions) => {
let appError: AppError

if (error instanceof AppError) {
Expand All @@ -81,7 +85,7 @@ export const handleAppError = (error: unknown) => {
addToast({
title: errorConfig.title,
description: appError.message || errorConfig.message,
timeout: 5000,
timeout: options?.timeout ?? 5000,
variant: 'solid',
color: 'danger',
shouldShowTimeoutProgress: true,
Expand Down
31 changes: 30 additions & 1 deletion frontend/src/utils/helpers/apolloClient.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,15 +3,44 @@ import { setContext } from '@apollo/client/link/context'
import { AppError, handleAppError } from 'app/global-error'
import { GRAPHQL_URL } from 'utils/env.client'
import { getCsrfToken } from 'utils/utility'

let hasShownGraphQLConnectionError = false

const notifyGraphQLConnectionError = () => {
if (hasShownGraphQLConnectionError) {
return
}

hasShownGraphQLConnectionError = true
handleAppError(
new AppError(
500,
'Unable to reach the GraphQL backend. Ensure the backend service is running and NEXT_PUBLIC_GRAPHQL_URL points to a valid /graphql/ endpoint.'
),
{ timeout: 12000 }
)
}

const createApolloClient = () => {
if (!GRAPHQL_URL) {
const error = new AppError(500, 'Missing GraphQL URL')
const error = new AppError(
500,
'Missing NEXT_PUBLIC_GRAPHQL_URL. Set it in frontend/.env and ensure the backend GraphQL service is running.'
)
handleAppError(error)
return null
}

const httpLink = new HttpLink({
credentials: 'include',
fetch: async (uri, options) => {
try {
return await fetch(uri, options)
} catch (error) {
notifyGraphQLConnectionError()
throw error
}
},
uri: GRAPHQL_URL,
})

Expand Down
13 changes: 11 additions & 2 deletions frontend/src/wrappers/provider.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,8 +24,17 @@ export function Providers({
}>) {
if (!apolloClient) {
return (
<div className="flex min-h-screen items-center justify-center text-red-500">
Configuration Error: GraphQL Client failed to initialize
<div className="flex min-h-screen items-center justify-center px-4 text-red-500">
<div className="max-w-2xl text-center">
<h1 className="text-xl font-semibold">GraphQL client is not configured</h1>
<p className="mt-2 text-sm text-foreground-700">
The frontend could not initialize Apollo because the GraphQL endpoint is unavailable.
</p>
<p className="mt-2 text-sm text-foreground-700">
<strong>Set NEXT_PUBLIC_GRAPHQL_URL in frontend/.env</strong> and ensure the backend GraphQL service
is running.
</p>
</div>
</div>
)
}
Expand Down