Troubleshoot agent work

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 SysthemaLink to this section

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 staleLink to this section

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 and Doctor.

The docs describe an unavailable APILink to this section

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, then installed declarations and source as an offline fallback. State the limitation.

MCP installation failsLink to this section

If the CLI reports an unknown mcp command, its version does not provide the installer. Use manual configuration, 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 effectLink to this section

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 wrongLink to this section

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.

A custom block disappears only in previewLink to this section

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 and client preview.

Production build cannot reach the databaseLink to this section

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.

SYSTHEMA_PRERENDER=off pnpm build

See Launch.

Upgrade requests unexpected schema changesLink to this section

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 and rehearse against a copy of the database.

The agent says done without evidenceLink to this section

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.