> Documentation index for m4trix: https://m4trix.dev/llms.txt. Every page is available as Markdown by appending `.md` to its URL.

# FAQ / Troubleshooting

Source: https://m4trix.dev/docs/project/faq-troubleshooting

## Installation

### Peer dependency warnings

Matrix uses [Effect](https://effect.website/) for schema validation. It's included as a dependency — no extra setup needed. If you see peer dependency warnings, ensure your Node.js and package manager versions are compatible.

### TypeScript errors

Ensure you have `"moduleResolution": "bundler"` or `"node16"` in your `tsconfig.json` if you use modern imports. m4trix ships with TypeScript types.

## Runtime

### SSE not streaming / connection hangs

- Ensure your deployment platform supports streaming responses (Vercel, Node.js do; some edge runtimes may not)
- Check that the client channel has `proxy.sse()` attached
- Verify `expose()` has `channel: 'client'` (or your output channel name)

### Events not reaching the agent

- Confirm the agent is registered with `subscribe(main)` (or the channel where start events are published)
- Check that the start event name in `expose()` matches the event your agent `listensTo`
- Ensure the payload schema matches — invalid payloads may be rejected before reaching the agent

### Auth failing

- The `auth` callback receives a request-like object. Ensure you're reading headers correctly (e.g. `req.request?.headers?.get?.('authorization')`)
- Return `{ allowed: false, message: '...', status: 401 }` for auth failures

### An agent sees no history (or another conversation's history is missing)

- History is namespaced by the principal `auth` returns: the same `contextId` under two principals (or anonymous vs. signed in) is two conversations. Check that `auth` returns the same `principal.id` for the user's requests
- Transient events are never stored, so they never appear in `ctx.history`
- The default in-memory store drops a conversation 30 minutes after its last event and keeps at most 1000; it is per process. Pass a persistent `store` to `AgentNetwork.setup()` for longer-lived history

## Evals

### eval-agents-simple not found

Ensure `@m4trix/evals` is installed and the CLI is in your `node_modules/.bin`. Run via `pnpm exec eval-agents-simple` or add a script in `package.json`.

### Dataset or evaluator not found

- Check that your files use the correct suffixes (`.dataset.ts`, `.evaluator.ts`, `.test-case.ts`)
- Verify `m4trix-eval.config.ts` if you use custom discovery paths
- Names are matched by string or pattern — use exact names or glob patterns like `*Demo*`

## Getting Help

- [GitHub Issues](https://github.com/Pascal-Lohscheidt/m4trix/issues)
- [pascal@stepsailor.com](mailto:pascal@stepsailor.com)