Skip to content

The open-source agent harness - the runtime layer that turns an LLM into a working agent.

chore: improve error handling for loading schedules, agents, and environments (#962)

harshil-2096c2ccca5b469e
diff --git a/.changeset/schedules-load-error-ui.md b/.changeset/schedules-load-error-ui.md
new file mode 100644
index 000000000..48b38a5e4
--- /dev/null
+++ b/.changeset/schedules-load-error-ui.md
@@ -0,0 +1,5 @@
+---
+'@truefoundry/trueforge-ui': patch
+---
+
+Show clearer empty-state errors when schedules, agents, or environments fail to load, and map browser network noise to the fallback in getErrorMessage.
diff --git a/packages/trueforge-ui/src/atoms/AgentsLibrary.tsx b/packages/trueforge-ui/src/atoms/AgentsLibrary.tsx
index 6f46cefc2..357c6d3d6 100644
--- a/packages/trueforge-ui/src/atoms/AgentsLibrary.tsx
+++ b/packages/trueforge-ui/src/atoms/AgentsLibrary.tsx
@@ -733,7 +733,10 @@ export function AgentsLibrary({ onSelectAgent, headerStart }: AgentsLibraryProps
<div className="bg-secondary-bg/40 flex min-h-0 flex-1 flex-col">
{/* Not flex-col: overflow-hidden table chrome would clip instead of letting this scroll. */}
- <div className="min-h-0 flex-1 overflow-y-auto p-4" aria-label="Agents">
+ <div
+ className={cn('min-h-0 flex-1 overflow-y-auto p-4', error ? 'flex flex-col' : undefined)}
+ aria-label="Agents"
+ >
{isInitialLoading ? (
<div className="flex flex-col gap-2 p-1" role="status" aria-label="Loading agents">
{Array.from({ length: 6 }, (_, i) => (
@@ -741,7 +744,9 @@ export function AgentsLibrary({ onSelectAgent, headerStart }: AgentsLibraryProps
))}
</div>
) : error ? (
- <p className="text-failure-bg px-3 py-8 text-center text-sm">{error}</p>
+ <div role="alert" className="flex flex-1 flex-col items-center justify-center">
+ <EmptyScreen title="Couldn't load agents" description={error} className="h-auto min-h-0 flex-none py-0" />
+ </div>
) : agents.length === 0 && !hasPageNav ? (
<EmptyScreen
title="No Agents Found"
diff --git a/packages/trueforge-ui/src/atoms/environments/EnvironmentsPage.tsx b/packages/trueforge-ui/src/atoms/environments/EnvironmentsPage.tsx
index 7b96da7a7..3ebb8b041 100644
--- a/packages/trueforge-ui/src/atoms/environments/EnvironmentsPage.tsx
+++ b/packages/trueforge-ui/src/atoms/environments/EnvironmentsPage.tsx
@@ -15,6 +15,7 @@ import {
import { getErrorMessage } from '../../utils/getErrorMessage.js';
import { EmptyScreen, EmptyScreenQueryHighlight } from '../EmptyScreen.js';
import { auiButtonClass } from '../lib/buttonClasses.js';
+import { cn } from '../lib/cn.js';
import { formatRelativeTime } from '../lib/dateFormat.js';
import { PageHeader } from '../PageHeader.js';
import { Button } from '../primitives/Button.js';
@@ -91,7 +92,7 @@ export function EnvironmentsPage(_props: EnvironmentsPageProps) {
} catch (caught) {
if (gen !== loadGenRef.current) return;
if (!silent) {
- setError(getErrorMessage(caught, 'Failed to load environments'));
+ setError(getErrorMessage(caught, 'Check your connection and try again.'));
setEnvironments([]);
setNextPageToken(undefined);
setPreviousPageToken(undefined);
@@ -215,9 +216,15 @@ export function EnvironmentsPage(_props: EnvironmentsPageProps) {
}
/>
- <div className="min-h-0 flex-1 overflow-auto px-4 py-4">
+ <div className={cn('min-h-0 flex-1 overflow-auto px-4 py-4', error != null ? 'flex flex-col' : undefined)}>
{error != null ? (
- <p className="text-failure-bg px-3 py-8 text-center text-sm">{error}</p>
+ <div role="alert" className="flex flex-1 flex-col items-center justify-center">
+ <EmptyScreen
+ title="Couldn't load environments"
+ description={error}
+ className="h-auto min-h-0 flex-none py-0"
+ />
+ </div>
) : loading ? (
<div className="flex flex-col gap-2" role="status" aria-label="Loading environments">
{Array.from({ length: 5 }, (_, i) => (
diff --git a/packages/trueforge-ui/src/atoms/lib/useSearchAgentsList.ts b/packages/trueforge-ui/src/atoms/lib/useSearchAgentsList.ts
index 23a67b4aa..208da4c9c 100644
--- a/packages/trueforge-ui/src/atoms/lib/useSearchAgentsList.ts
+++ b/packages/trueforge-ui/src/atoms/lib/useSearchAgentsList.ts
@@ -192,7 +192,7 @@ export function useSearchAgentsList({
setNextPageToken(undefined);
setPreviousPageToken(undefined);
setHasMore(false);
- setError(getErrorMessage(err, 'Failed to load agents.'));
+ setError(getErrorMessage(err, 'Check your connection and try again.'));
})
.finally(() => {
if (gen === genRef.current) setLoading(false);
diff --git a/packages/trueforge-ui/src/atoms/schedules/SchedulesPage.tsx b/packages/trueforge-ui/src/atoms/schedules/SchedulesPage.tsx
index 7420dbd8c..18952d345 100644
--- a/packages/trueforge-ui/src/atoms/schedules/SchedulesPage.tsx
+++ b/packages/trueforge-ui/src/atoms/schedules/SchedulesPage.tsx
@@ -10,6 +10,7 @@ import { libraryAgentId } from '../../server/ShellModeContext.js';
import type { Schedule, ScheduleRun, ScheduleStatus } from '../../server/types.js';
import { useSlot } from '../../theme/SlotsProvider.js';
import { hasCreatedBySubject } from '../../utils/createdBySubject.js';
+import { getErrorMessage } from '../../utils/getErrorMessage.js';
import { readScheduleShareSearch, replaceScheduleShareSearch } from '../../utils/scheduleShareUrl.js';
import { AgentSearchPicker } from '../AgentSearchPicker.js';
import { CreatedByCell } from '../CreatedByCell.js';
@@ -238,8 +239,7 @@ export function SchedulesPage({ agentId }: SchedulesPageProps) {
void loadRunsForSchedules({ rows: page.data, gen });
} catch (caught) {
if (gen !== loadGenRef.current) return;
- const message = caught instanceof Error ? caught.message : 'Failed to load schedules';
- setError(message);
+ setError(getErrorMessage(caught, 'Check your connection and try again.'));
setSchedules([]);
setRunsByScheduleId({});
setNextPageToken(undefined);
@@ -433,7 +433,7 @@ export function SchedulesPage({ agentId }: SchedulesPageProps) {
}
/>
- <div className="min-h-0 flex-1 overflow-auto px-4 py-4">
+ <div className={cn('min-h-0 flex-1 overflow-auto px-4 py-4', error != null ? 'flex flex-col' : undefined)}>
{loading ? (
<div className="flex flex-col gap-2" role="status" aria-label="Loading schedules">
{Array.from({ length: 5 }, (_, i) => (
@@ -441,7 +441,13 @@ export function SchedulesPage({ agentId }: SchedulesPageProps) {
))}
</div>
) : error != null ? (
- <p className="text-failure-bg px-3 py-8 text-center text-sm">{error}</p>
+ <div role="alert" className="flex flex-1 flex-col items-center justify-center">
+ <EmptyScreen
+ title="Couldn't load schedules"
+ description={error}
+ className="h-auto min-h-0 flex-none py-0"
+ />
+ </div>
) : schedules.length === 0 ? (
<EmptyScreen title="No Schedules Found" description="Create one to get started." className="min-h-full" />
) : filtered.length === 0 ? (
diff --git a/packages/trueforge-ui/src/utils/getErrorMessage.ts b/packages/trueforge-ui/src/utils/getErrorMessage.ts
index db7b262bb..e336e4baf 100644
--- a/packages/trueforge-ui/src/utils/getErrorMessage.ts
+++ b/packages/trueforge-ui/src/utils/getErrorMessage.ts
@@ -125,28 +125,47 @@ function stringifyError(error: unknown): string {
return String(error);
}
+/** Browser fetch failures that are useless as UI copy when a fallback exists. */
+const BROWSER_NETWORK_NOISE = new Set([
+ 'failed to fetch',
+ 'load failed',
+ 'networkerror when attempting to fetch resource.',
+]);
+
+function isBrowserNetworkNoise(message: string): boolean {
+ return BROWSER_NETWORK_NOISE.has(message.trim().toLowerCase());
+}
+
+function preferFallbackForNetworkNoise(message: string, fallback: string | undefined): string {
+ if (fallback != null && isBrowserNetworkNoise(message)) {
+ return decodeErrorMessageEscapes(fallback);
+ }
+ return decodeErrorMessageEscapes(message);
+}
+
/**
* User-facing error text. Prefers HTTP body `{ error: { message } }` when
* present (e.g. TrueForgeError), then `error.message` / `error.error.message`,
* then `fallback`, then a string form of the value.
*
- * Escape sequences (`\n`, `\t`, `\r`, `\uXXXX`, …) are decoded for display when
- * still present as literal text.
+ * Browser network noise (`Failed to fetch`, etc.) yields `fallback` when one
+ * is provided. Escape sequences (`\n`, `\t`, `\r`, `\uXXXX`, …) are decoded for
+ * display when still present as literal text.
*/
export function getErrorMessage(error: unknown, fallback?: string): string {
if (typeof error === 'string') {
const trimmed = error.trim();
- if (trimmed !== '') return decodeErrorMessageEscapes(error);
+ if (trimmed !== '') return preferFallbackForNetworkNoise(error, fallback);
return fallback != null ? decodeErrorMessageEscapes(fallback) : decodeErrorMessageEscapes(error);
}
if (isRecord(error) && 'body' in error) {
const fromBody = messageFromErrorShaped(error.body);
- if (fromBody != null) return decodeErrorMessageEscapes(fromBody);
+ if (fromBody != null) return preferFallbackForNetworkNoise(fromBody, fallback);
if (error.body != null) {
if (typeof error.body === 'string') {
const trimmed = error.body.trim();
- if (trimmed !== '') return decodeErrorMessageEscapes(error.body);
+ if (trimmed !== '') return preferFallbackForNetworkNoise(error.body, fallback);
} else {
return stringifyError(error.body);
}
@@ -154,7 +173,7 @@ export function getErrorMessage(error: unknown, fallback?: string): string {
}
const fromShape = messageFromErrorShaped(error);
- if (fromShape != null) return decodeErrorMessageEscapes(fromShape);
+ if (fromShape != null) return preferFallbackForNetworkNoise(fromShape, fallback);
if (fallback != null) return decodeErrorMessageEscapes(fallback);
return stringifyError(error);
diff --git a/packages/trueforge-ui/test/atoms/AgentsLibrary.test.tsx b/packages/trueforge-ui/test/atoms/AgentsLibrary.test.tsx
index 973f6deb9..16cbd8bde 100644
--- a/packages/trueforge-ui/test/atoms/AgentsLibrary.test.tsx
+++ b/packages/trueforge-ui/test/atoms/AgentsLibrary.test.tsx
@@ -140,6 +140,22 @@ describe('CenteredModal', () => {
});
describe('AgentsLibrary', () => {
+ it('shows a friendly load error instead of raw fetch failures', async () => {
+ const server = createMockAgentUIServer({
+ searchAgents: vi.fn(async () => {
+ throw new TypeError('Failed to fetch');
+ }),
+ });
+ renderLibrary(<LibraryHarness />, { server });
+ fireEvent.click(screen.getByRole('button', { name: 'Open library' }));
+
+ expect(await screen.findByRole('heading', { name: "Couldn't load agents" })).toBeInTheDocument();
+ expect(screen.getByText('Check your connection and try again.')).toBeInTheDocument();
+ expect(screen.queryByText('Failed to fetch')).not.toBeInTheDocument();
+ expect(screen.queryByText('Failed to load agents.')).not.toBeInTheDocument();
+ expect(screen.queryByRole('button', { name: 'Retry' })).not.toBeInTheDocument();
+ });
+
it('opens agent details from the row only when the optional server is available', async () => {
window.history.replaceState(null, '', '/library?theme=dark&sessionId=stale&view=sessions&s_sts=1&s_ets=2');
const server = createMockAgentUIServer({
diff --git a/packages/trueforge-ui/test/atoms/environments/EnvironmentsPage.test.tsx b/packages/trueforge-ui/test/atoms/environments/EnvironmentsPage.test.tsx
index d1edc68e8..53f47a818 100644
--- a/packages/trueforge-ui/test/atoms/environments/EnvironmentsPage.test.tsx
+++ b/packages/trueforge-ui/test/atoms/environments/EnvironmentsPage.test.tsx
@@ -108,6 +108,22 @@ describe('EnvironmentsPage', () => {
expect(screen.getByText('1 allowed domain')).toBeInTheDocument();
});
+ it('shows a friendly load error instead of raw fetch failures', async () => {
+ renderPage({
+ environmentOverrides: {
+ listEnvironments: vi.fn(async () => {
+ throw new TypeError('Failed to fetch');
+ }),
+ },
+ });
+
+ expect(await screen.findByRole('heading', { name: "Couldn't load environments" })).toBeInTheDocument();
+ expect(screen.getByText('Check your connection and try again.')).toBeInTheDocument();
+ expect(screen.queryByText('Failed to fetch')).not.toBeInTheDocument();
+ expect(screen.queryByText('Failed to load environments')).not.toBeInTheDocument();
+ expect(screen.queryByRole('button', { name: 'Retry' })).not.toBeInTheDocument();
+ });
+
it('opens create drawer from New Environment', async () => {
renderPage();
await waitFor(() => {
diff --git a/packages/trueforge-ui/test/atoms/lib/useSearchAgentsList.test.tsx b/packages/trueforge-ui/test/atoms/lib/useSearchAgentsList.test.tsx
index a1e47a18b..4f5b475c0 100644
--- a/packages/trueforge-ui/test/atoms/lib/useSearchAgentsList.test.tsx
+++ b/packages/trueforge-ui/test/atoms/lib/useSearchAgentsList.test.tsx
@@ -218,4 +218,17 @@ describe('useSearchAgentsList', () => {
expect(result.current.canNext).toBe(false);
expect(result.current.canPrev).toBe(false);
});
+
+ it('maps browser network noise to a friendly error', async () => {
+ const searchAgents = vi.fn(async () => {
+ throw new TypeError('Failed to fetch');
+ });
+ const server = createMockAgentUIServer({ searchAgents });
+ const { result } = renderHook(() => useSearchAgentsList({ enabled: true, query: '', mode: 'paged', limit: 10 }), {
+ wrapper: wrapperFor(server),
+ });
+
+ await waitFor(() => expect(result.current.error).toBe('Check your connection and try again.'));
+ expect(result.current.agents).toEqual([]);
+ });
});
diff --git a/packages/trueforge-ui/test/atoms/schedules/SchedulesPage.test.tsx b/packages/trueforge-ui/test/atoms/schedules/SchedulesPage.test.tsx
index 2b4ed0078..bc1d6f8a2 100644
--- a/packages/trueforge-ui/test/atoms/schedules/SchedulesPage.test.tsx
+++ b/packages/trueforge-ui/test/atoms/schedules/SchedulesPage.test.tsx
@@ -122,6 +122,17 @@ describe('SchedulesPage', () => {
expect(searchAgents).not.toHaveBeenCalled();
});
+ it('shows a friendly load error instead of raw fetch failures', async () => {
+ renderPage(sampleSchedules, {}, async () => {
+ throw new TypeError('Failed to fetch');
+ });
+
+ expect(await screen.findByRole('heading', { name: "Couldn't load schedules" })).toBeInTheDocument();
+ expect(screen.getByText('Check your connection and try again.')).toBeInTheDocument();
+ expect(screen.queryByText('Failed to fetch')).not.toBeInTheDocument();
+ expect(screen.queryByRole('button', { name: 'Retry' })).not.toBeInTheDocument();
+ });
+
it('disables schedule mutations without MANAGE or DELETE', async () => {
const { scheduleServer } = renderPage(sampleSchedules, {}, undefined, undefined, {
agentId: 'demo-agent',
diff --git a/packages/trueforge-ui/test/utils/getErrorMessage.test.ts b/packages/trueforge-ui/test/utils/getErrorMessage.test.ts
index 8ff68c1a1..7bf314e83 100644
--- a/packages/trueforge-ui/test/utils/getErrorMessage.test.ts
+++ b/packages/trueforge-ui/test/utils/getErrorMessage.test.ts
@@ -75,4 +75,25 @@ describe('getErrorMessage', () => {
it('reads plain Error.message', () => {
expect(getErrorMessage(new Error('boom'), 'fallback')).toBe('boom');
});
+
+ it('uses fallback for browser network noise when provided', () => {
+ expect(getErrorMessage(new TypeError('Failed to fetch'), 'Check your connection.')).toBe('Check your connection.');
+ expect(getErrorMessage(new TypeError('Load failed'), 'Check your connection.')).toBe('Check your connection.');
+ expect(
+ getErrorMessage(new TypeError('NetworkError when attempting to fetch resource.'), 'Check your connection.'),
+ ).toBe('Check your connection.');
+ expect(getErrorMessage('Failed to fetch', 'Check your connection.')).toBe('Check your connection.');
+ });
+
+ it('keeps browser network noise when no fallback is provided', () => {
+ expect(getErrorMessage(new TypeError('Failed to fetch'))).toBe('Failed to fetch');
+ });
+
+ it('prefers HTTP body over browser network noise on the Error message', () => {
+ const err = Object.assign(new TypeError('Failed to fetch'), {
+ statusCode: 503,
+ body: { error: { message: 'Service unavailable' } },
+ });
+ expect(getErrorMessage(err, 'Check your connection.')).toBe('Service unavailable');
+ });
});