The open-source agent harness - the runtime layer that turns an LLM into a working agent.
---
title: "Troubleshooting"
description: "Common failure modes and their causes."
---
<AccordionGroup>
<Accordion title="Error: requires an AuiProvider">
Deduplicate the assistant-ui singletons `react`, `react-dom`, `@assistant-ui/core`, `@assistant-ui/react`, and `@assistant-ui/store` must each resolve to exactly one copy in your bundle. Two copies produce a runtime error along the lines of _"requires an AuiProvider"_.
<CodeGroup>
```ts vite.config.ts
export default defineConfig({
resolve: {
dedupe: [
"react",
"react-dom",
"@assistant-ui/core",
"@assistant-ui/react",
"@assistant-ui/store",
],
},
});
```
```json package.json
{
"resolutions": {
"@assistant-ui/core": "<version>",
"@assistant-ui/store": "<version>"
}
}
```
</CodeGroup>
The `vite.config.ts` approach is usually enough. Reach for `resolutions` (or `overrides` on npm, `pnpm.overrides` on pnpm) when a transitive dependency drags in a second copy.
Note that `@assistant-ui/store` arrives transitively through `@assistant-ui/core` rather than being declared by the SDK, so there is no published version to look up — pin it to whatever your lockfile resolves `@assistant-ui/core` against.
</Accordion>
<Accordion title="The UI renders but is collapsed to zero height">
The SDK fills its parent container and does not set its own height. A parent with no resolved height collapses the entire chat UI, which is the single most common cause of a "blank" first install.
```tsx
<div className="flex h-dvh min-h-0 w-full flex-1 flex-col">
<TrueForgeUI /* ... */ className="h-full min-h-0" />
</div>
```
The SDK fills its parent container and does not set its own height. A parent with no resolved height collapses the entire chat UI, which is the single most common cause of a "blank" first install.
</Accordion>
<Accordion title="The SDK renders unstyled">
Check that `@import "@truefoundry/trueforge-ui/styles.css";` is actually reaching the browser — that single import is the entire styling setup, and the stylesheet is self-contained. You do not need Tailwind in your own app for the SDK to look right.
</Accordion>
<Accordion title="Your app's own base styles changed after installing">
The SDK's stylesheet deliberately omits Tailwind preflight so it cannot reset your styles, so this is unlikely to come from the import itself. Look instead at whether you added `@import "tailwindcss";` at the same time — that one does ship preflight, and it resets host styles by design.
</Accordion>
<Accordion title="An error alert appears immediately on mount">
The built-in server failed to resolve. For `type: "trueforge"`, confirm `@truefoundry/trueforge-sdk`
is installed, `baseUrl` is reachable, and you passed either `token` or a working `fetch` — see
[Quickstart](/ui-sdk/get-started/quickstart). Attach an `onError` handler to see the underlying error.
</Accordion>
<Accordion title="Requests fail in composer mode with an unknown model">
Without an explicit `defaultAgentSpec`, drafts default to `openai-main/gpt-4.1`. Pass a spec naming a model your backend actually exposes: `agentConfig={{ mode: "AgentComposer", defaultAgentSpec: { model: { name: "..." } } }}`.
</Accordion>
<Accordion title="Changing defaultAgentSpec did not affect the open conversation">
It seeds a new draft rather than binding to the current one, so the change lands on the next **new chat**. Clear chat will not pick it up — that path preserves the spec already bound to the draft. To apply it to the conversation on screen, remount the component with a new `key`. It is ignored entirely in `SingleAgent` mode.
</Accordion>
<Accordion title="The settings button is missing">
Settings render only when your server exposes a `catalog`, so attach one to enable the panel. If you are on a custom layout, that is the other cause — the panel ships with the built-in layouts only.
</Accordion>
<Accordion title="Only the OAuth screen renders — no chat">
A `screenType=mcp-auth` query parameter is present on the URL. `TrueForgeUI` renders the OAuth completion screen exclusively in that case. Keep the callback on its own route; see [MCP OAuth](/ui-sdk/setup-custom-ui/mcp-oauth).
</Accordion>
<Accordion title="Dark mode fights with the host application">
The provider toggles the `dark` class on `document.documentElement`. Pass a controlled `theme.mode` derived from your own state so the two stay aligned.
</Accordion>
<Accordion title="Import of AskUserPrompt fails">
A few names are published as types only, so importing them as values fails.
`AskUserPrompt`, `McpAuthPrompt`, and `ReasoningCard` are override-only — supply your own
component typed with the published props. `Button` / `IconButton` are public values restyled
through [theme tokens](/ui-sdk/setup-custom-ui/custom-theme), not slot overrides.
</Accordion>
<Accordion title="SSR or React Server Components errors">
The package is ESM-only and client-only. Mount `TrueForgeUI` from a client component — in Next.js App Router, a file with `"use client"` at the top.
</Accordion>
</AccordionGroup>