> ## Documentation Index
> Fetch the complete documentation index at: https://pdfn.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Handle pdfn errors with the { data, error } response pattern. Includes error codes, common issues like connection failures, and step-by-step fixes.

Every `generate()` and `render()` call returns `{ data, error }` instead of throwing. Check `error` before using `data`.

## Basic pattern

```typescript theme={null}
const { data, error } = await client.generate({ react: <Invoice /> });

if (error) {
  console.error(error.code, error.message);
  return;
}

// Success - use data.buffer
```

## Error object

`PdfnError` is a class that extends `Error`:

```typescript theme={null}
import { PdfnError } from '@pdfn/react';

class PdfnError extends Error {
  code: PdfnErrorCode;      // Machine-readable code
  message: string;           // Human-readable message
  suggestion?: string;       // How to fix it
  statusCode?: number;       // HTTP status (if applicable)
}
```

You can use `instanceof` to check for pdfn errors:

```typescript theme={null}
import { PdfnError } from '@pdfn/react';

if (error instanceof PdfnError) {
  console.error(`[${error.code}] ${error.message}`);
  if (error.suggestion) {
    console.error(`Fix: ${error.suggestion}`);
  }
}
```

## Error codes

| Code                   | Cause                    | Solution                                                                   |
| ---------------------- | ------------------------ | -------------------------------------------------------------------------- |
| `configuration_error`  | Missing server config    | Run `npx pdfn dev` or set `PDFN_API_KEY`                                   |
| `authentication_error` | Invalid API key          | Check your `PDFN_API_KEY`                                                  |
| `validation_error`     | Invalid input            | Check your template or options                                             |
| `rate_limit_error`     | Too many requests        | Wait and retry, or upgrade at [console.pdfn.dev](https://console.pdfn.dev) |
| `timeout_error`        | Generation took too long | Simplify template or increase timeout                                      |
| `network_error`        | Can't reach server       | Check connection, run `npx pdfn dev`                                       |
| `render_error`         | React render failed      | Check component for errors                                                 |
| `server_error`         | Server-side error        | Retry, or contact support at [console.pdfn.dev](https://console.pdfn.dev)  |

## Common issues

### Cannot connect to pdfn server

```text theme={null}
[network_error] Cannot connect to pdfn server at http://localhost:3456
```

The dev server isn't running. Start it in a separate terminal:

```bash theme={null}
npx pdfn dev
```

### PDF generation timed out

```text theme={null}
[timeout_error] PDF generation timed out
```

Simplify your template or increase the timeout:

```typescript theme={null}
const client = pdfn({
  timeout: 60000, // 60 seconds
});
```

### Invalid API key

```text theme={null}
[authentication_error] Invalid API key.
```

Check that `PDFN_API_KEY` is set correctly in your environment. Keys start with `pdfn_test_` or `pdfn_live_`. Get a new key at [console.pdfn.dev](https://console.pdfn.dev).

### render() called in the browser

```text theme={null}
render() can only be used on the server.
```

`render()` uses `react-dom/server` which isn't available in browsers. In Next.js, make sure this code runs in a Server Component or API route — not a Client Component.

### Local fonts or images on edge runtimes

```text theme={null}
Local font paths detected: ./fonts/custom.woff2
Edge runtimes don't have filesystem access.
```

Edge runtimes (Vercel Edge, Cloudflare Workers) can't read local files. Options:

* Use Google Fonts instead of local font files
* Use remote URLs for images instead of local paths
* Pre-encode assets as base64 data URIs
* Switch to Node.js runtime (Vercel Serverless instead of Edge)

### Client components not rendering

Templates that use `"use client"` components (like chart libraries) need a build plugin. Make sure `@pdfn/next` or `@pdfn/vite` is installed and configured:

```ts theme={null}
// next.config.ts
import { withPdfn } from '@pdfn/next';
export default withPdfn()(nextConfig);

// vite.config.ts
import { pdfn } from '@pdfn/vite';
export default { plugins: [pdfn()] };
```

See [Next.js](/nextjs#client-components) for details.

### React component threw during render

```text theme={null}
[render_error] Failed to render: ...
```

Common causes:

* Using async components (not supported in static rendering)
* Component threw an error during render
* Invalid React element passed to `render()`

Check your template renders correctly in `npx pdfn dev` before calling `generate()`.

***

## Next steps

<CardGroup cols={2}>
  <Card title="Components" icon="cube" href="/components">
    Document, Page, and layout components
  </Card>

  <Card title="Generate & Render" icon="file-pdf" href="/generate">
    Client setup, generate() and render() parameters
  </Card>
</CardGroup>