Improve GraphQL and backend connectivity error messaging in frontend

[hassaansaleem28]

Proposed change

Resolves #4308

Summary

This PR improves frontend error handling when GraphQL is not configured or if the backend is not running, so new contributors receive clearer setup guidance during local onboarding.

BEFORE:

AFTER:

When backend is not running:

Checklist

• Required: I followed the contributing workflow
• Required: I verified that my code works as intended and resolves the issue as described
• Required: I ran make check-test locally: all warnings addressed, tests passed
• I used AI for code, documentation, tests, or communication related to this PR

[coderabbitai]

Walkthrough

The PR improves error handling and user messaging when the GraphQL client is not configured. Changes include: adding optional timeout configuration to the global error handler, introducing a GraphQL connection error notification mechanism, and replacing the generic error message with a detailed setup guide explaining environment variables and backend service requirements.

Changes

Cohort / File(s)	Summary
Error Handler Configuration frontend/src/app/global-error.tsx	Added HandleAppErrorOptions interface with optional timeout field; handleAppError now accepts options parameter to customize toast timeout duration (defaults to 5000ms).
GraphQL Connection Error Handling frontend/src/utils/helpers/apolloClient.ts	Implemented one-time GraphQL connection error notification mechanism with 12s timeout option; fetch errors in HttpLink are now caught and notified before being rethrown. Enhanced missing-URL error message to reference NEXT_PUBLIC_GRAPHQL_URL.
Error UI Messaging frontend/src/wrappers/provider.tsx	Replaced generic "Configuration Error" fallback message with detailed, responsive error panel including setup instructions for NEXT_PUBLIC_GRAPHQL_URL environment variable and backend service verification.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• Fix 404 flash on About page #3124: Related changes to the handleAppError API expansion with timeout options for customizable error notifications.

Suggested labels

frontend

Suggested reviewers

• arkid15r
• kasya

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main change: improving error messaging for GraphQL and backend connectivity issues in the frontend.
Linked Issues check	✅ Passed	The PR fully addresses issue #4308 by implementing clearer error messages with setup guidance, improved initialization error UI, and runtime GraphQL connection error notifications.
Out of Scope Changes check	✅ Passed	All changes are directly related to improving GraphQL and backend connectivity error messaging as required by issue #4308; no out-of-scope modifications detected.
Description check	✅ Passed	The pull request description clearly relates to the changeset, explaining improvements to frontend GraphQL error handling for better contributor onboarding with before/after screenshots.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

🧹 Nitpick comments (1)

frontend/src/utils/helpers/apolloClient.ts (1)

7-22: Reset one-time GraphQL connection toast after recovery.

On Line 14, the guard is latched permanently. After one outage, later outages in the same session won’t show the connectivity guidance again. Consider resetting after a successful request.

Proposed refactor

 let hasShownGraphQLConnectionError = false
@@
     fetch: async (uri, options) => {
       try {
-        return await fetch(uri, options)
+        const response = await fetch(uri, options)
+        // Backend is reachable again; allow future outage notifications.
+        hasShownGraphQLConnectionError = false
+        return response
       } catch (error) {
         notifyGraphQLConnectionError()
         throw error
       }
     },

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@frontend/src/utils/helpers/apolloClient.ts` around lines 7 - 22, The code
latches hasShownGraphQLConnectionError permanently in
notifyGraphQLConnectionError so subsequent outages in the same session never
re-show the toast; modify the Apollo client success path to reset that latch
after recovery by setting hasShownGraphQLConnectionError = false when a GraphQL
request succeeds (e.g., in the Apollo link response handler or the fetch/execute
success callback that you use when creating the client). Update the relevant
places (the notifyGraphQLConnectionError function remains the same) and ensure
the reset occurs on any successful response or onError recovery path so the
toast can reappear for future outages.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@frontend/src/utils/helpers/apolloClient.ts`:
- Around line 7-22: The code latches hasShownGraphQLConnectionError permanently
in notifyGraphQLConnectionError so subsequent outages in the same session never
re-show the toast; modify the Apollo client success path to reset that latch
after recovery by setting hasShownGraphQLConnectionError = false when a GraphQL
request succeeds (e.g., in the Apollo link response handler or the fetch/execute
success callback that you use when creating the client). Update the relevant
places (the notifyGraphQLConnectionError function remains the same) and ensure
the reset occurs on any successful response or onError recovery path so the
toast can reappear for future outages.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 99625a4e-9a57-4451-a67c-e6d2bff6f217

📥 Commits

Reviewing files that changed from the base of the PR and between a148dd2 and 4795497.

📒 Files selected for processing (3)

• frontend/src/app/global-error.tsx
• frontend/src/utils/helpers/apolloClient.ts
• frontend/src/wrappers/provider.tsx

[cubic-dev-ai]

No issues found across 3 files

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud