---
title: "Troubleshoot agent work"
description: "Recover from missing references, version mismatches, rendering failures and incomplete verification."
requested_language: nl
language: en
translation_notice: "This page isn't translated yet"
url: https://docs.systhema.app/nl/ai-agents/troubleshooting
version: unreleased (main)
docs_index: https://docs.systhema.app/nl/llms.txt
---
> This page isn't translated yet. Showing English.


Start with the actual error and installed version. Identify whether the failure is documentation lookup, token generation, rendering, preview or database migration before changing code.

## The agent cannot identify Systhema

Inspect the app's `package.json`, `.systhema/` and `systhema.config.ts`. A workspace root may not declare the same dependencies as its app. Move to the consumer app before running local scripts.

A blank directory is valid only when the task explicitly creates a Systhema project or design. Do not apply Systhema instructions to another framework because a component happens to be called Section or Card.

## Token references are missing or stale

```bash
pnpm sync
cat .systhema/references/tokens/_index.toon
systhema doctor
```

Check the manifest paths and config. Re-read the collection references after sync. Do not repair generated TOON or artifacts by hand. Use [Generated artifacts](https://docs.systhema.app/nl/concepts/generated-artifacts.md) and [Doctor](https://docs.systhema.app/nl/cli/doctor.md).

## The docs describe an unavailable API

Read the installed version again, then call `resolve_docs_version` with it. Check that search and page reads use the same version. `latest` is not a substitute for an older project.

If the dependency tree is unavailable, use the package range and label the fallback. If the service is unavailable, use the [HTTP protocol](docs-for-agents.md), then installed declarations and source as an offline fallback. State the limitation.

## MCP installation fails

If the CLI reports an unknown `mcp` command, its version does not provide the installer. Use [manual configuration](mcp-server.md), reconnect the agent and confirm all five tools.

A missing docs page may be a path mismatch. Use `list_docs` with `area`, read the closest-path suggestions and request an actual heading slug. Do not retry with invented API names or switch to an unrelated MCP server.

## A variant or theme has no visible effect

Confirm its exact name in the project references. Check whether the code uses a named variant and whether a parent theme scope or background is overriding the intended region.

Render the component and inspect the result. Types alone cannot prove a name exists at runtime after a stale generation step.

## Width or spacing looks wrong

Check composition first:

- Is Article present around code-owned page sections?
- Did a wrapper break direct-child rich-text spacing?
- Did a template Section wrap a block that supplies another Section?
- Did `padding={n}` unintentionally narrow the horizontal grid inset?
- Did adjacent sections intentionally merge because their theme and ground match?
- Did a vertical Stack replace the prose rhythm?

Remove the extra constraint before adjusting token values. See [Spacing model](https://docs.systhema.app/nl/concepts/spacing-model.md).

## A custom block disappears only in preview

Published server registration and browser registration are separate. Configure `livePreview.clientSetup` with a module-scope `registerSysthemaClientBlocks` call. Import browser-safe converter modules directly.

For transitive server/client boundary errors, inspect the whole import chain, not only the file with `'use client'`. A converter importing an interactive component can fail during the server pass of a client template. Test a static renderer or move interaction into a separately mounted client controller as the relevant component requires.

See the [custom-block tutorial](https://docs.systhema.app/nl/guides/build-a-site/custom-block.md) and [client preview](https://docs.systhema.app/nl/payload/frontend/live-preview/client-mode.md).

## Production build cannot reach the database

Use `SYSTHEMA_PRERENDER=off` for a private-network build and keep the managed catch-all's lazy Payload getter. Runtime requests still need database access. Audit custom routes for their own build-time queries.

```bash
SYSTHEMA_PRERENDER=off pnpm build
```

See [Launch](https://docs.systhema.app/nl/guides/build-a-site/launch.md).

## Upgrade requests unexpected schema changes

Stop before accepting a drop or ambiguous rename. Read the release notes and inspect the site's database lane. Rename hooks run before schema push; shape changes use project-owned migrations. The additive PostgreSQL `systhema migrate --schema` path is for push-only databases, not a replacement for migration history.

Use [Upgrading a client site](https://docs.systhema.app/nl/guides/recipes/upgrading-a-client-site.md) and rehearse against a copy of the database.

## The agent says done without evidence

Request the changed paths, docs version, commands with exit status and behavior observed. Require public rendering and preview checks for block work, actual delivery for email, and preserved records for migrations. Mark checks that were not run as unverified.