Troubleshooting — deco developer docs

Esta página ainda não foi traduzida para o português — o conteúdo abaixo está em inglês.

A page shows old content after a deploy, or a block comes back as an error instead of rendering. This page shows the first things to check, then common symptoms and what to check for each.

First checks

Most problems come down to three facts: which revision this server is serving, which entry was asked for, and which block type it names. Log await client.revision(): that's the revision this server serves. The content module, .deco/blocks.gen.ts, holds the same value, so you can compare it with a fresh deco content run on the commit you expect. To see an entry with references expanded but no function run, call client.resolve(target, { run: false }). To see it exactly as stored, open .deco/blocks/<name>.json.

Symptoms

Errors

Symptom	What to check
`UNKNOWN_BLOCK`	A `__resolveType` names something that is in neither the block map nor the saved blocks. Built-in blocks never cause it. Compare `__resolveType` with your block map's keys, including case. Add an alias for renamed types.
`NOT_FOUND`	A string target is always a saved block's name, never a block type. Confirm the entry exists in the served revision, that `createCMS`'s `content` is the content you expect, and that `deco content` ran after the file was added (see The content module). To run a type directly, pass an inline block: `client.resolve({ __resolveType: "seo", … })`.
`CYCLE`	Follow the references in `error.path` and remove the one that leads back to an entry already being expanded (see The rule in full).
`UNKNOWN_BLOCK` right after a content change	The content uses a block type its code doesn't have yet, or no longer has. Ship the code in the same change, or revert the content commit. See Backward compatibility.
Warning about an instance with different options	`createCMS` ran twice with the same content but different options. The first instance is kept. Create the CMS once, at module scope (see One instance per process).

Content and deploys

Symptom	What to check
My saved block is ignored	A block type probably has the same name, and the function wins. Run `npx @decocms/blocks check`, which reports the collision, and rename the entry.
Blocks come back as JSON instead of running	You called `client.list` without `{ run: true }` (it returns saved blocks by default), or you passed `{ run: false }` to `resolve`. To run listed entries, pass `run: true`, or resolve each listed entry with `client.resolve(entry)` (a page comes back fully resolved).
A function runs more than once per request	A client runs each block once and reuses the result, but only within that client and for that block map object. Make one client per request, not per component, and create the block map at module level, not inside your handler.
Content changes mid-response	Use one client for the whole response; a client never changes revision. If you pass a custom `content` object, check that it never returns different content under an existing revision.
Old content after a deploy	Compare the revision your server logs (see above) with the one in `.deco/blocks.gen.ts` after running `npx @decocms/blocks content` on your latest commit. If they differ, the build didn't rerun `deco content`: check that `prebuild` runs `deco schema && deco content && deco check` and that the build checked out the commit you expect. See Deployment.
A scheduled campaign went live late, or still shows after it ended	A cached or statically rendered page keeps its variant. See Pages with variants and the Next.js caching note.
A new content file isn't found in development	Run `npx @decocms/blocks content`, or keep `npx @decocms/blocks content --watch` running beside your dev server. Only adding or removing a file needs it; edits to an existing file hot-reload.

Rendering

Symptom	What to check
Serialization error when sending a block's result to the browser	JSON can't carry functions or React elements. Return descriptors, or render on the server with RSC (see Rendering).
Hydration mismatch (React's browser render doesn't match the server's HTML)	Look for time-dependent or random rendering, and for request context the server and browser see differently. If the browser fetches data after the page loads, it may get a newer revision; render data that must match the HTML in the same response.

CLI

Symptom	What to check
`no .deco/ found` when running a `deco` command	The command walks up from the current folder and found no `.deco/`. Run it inside your app, or pass `--root <dir>` (see Finding the `.deco` folder).
Type errors in `.deco/index.ts` aren't reported	TypeScript's `include` patterns skip folders whose names start with a dot, so `.deco/index.ts` is only checked when an included file imports it (usually your `cms.ts`). To always check it, add `".deco"` to `include` in `tsconfig.json`.
`deco check` fails	It lists each problem under the file it's in. A missing required field or an out-of-range value: fix the saved block, or make the field optional in your type. `unknown block type`: add the type to your block map, add an alias if you renamed it, or fix the `__resolveType`. Run `npx @decocms/blocks schema` first, since it validates against `schema.gen.json` as it is. See Checking content and Backward compatibility.
`deco: command not found`	In a terminal, run `npx @decocms/blocks <command>`. The short name `deco` works inside `package.json` scripts once `@decocms/blocks` is installed; if a script can't find it, run `npm install` (see CLI).
`Cannot find package 'typescript'` when running a `deco` command	The CLI uses your project's TypeScript. npm and Bun install it with `@decocms/blocks`; with another package manager, run `npm install -D typescript` (or its equivalent).

Site editor

Symptom	What to check
Wrong fields in the editor	Regenerate the schema from the right `.deco/index.ts` (check `--root` in a monorepo). Check the first parameter's type and its property JSDoc (see From types to forms).
The site editor can't reach `deco serve`	Check that the server is still running: while it's down, the site editor shows that it's waiting for it and reconnects once it's back. Use the endpoint `deco serve` printed (`localhost` with its port). Allow the browser's prompt to let the site editor reach your machine (Local Network Access). See Edit on your machine.
The site editor shows plain fields and a banner about the schema	The site has no schema yet (`.deco/schema.gen.json`), so each block opens as fields inferred from its JSON, grouped by `__resolveType`. Saving keeps every value you didn't touch. Run `npx @decocms/blocks schema` in the site's folder: the site editor picks the schema up on its own and shows the typed forms (see No schema yet).
A form field in the site editor is a text box instead of a picker	The site editor never runs your code (see What works without your code), so options that would come from a function aren't available. Give the field a string-literal union, an enum or an `@options` list, and run `npx @decocms/blocks schema` (see Widgets).
A preview shows published content instead of the draft	The host may be outside your preview hosts: `cms.draftPointer` ignores drafts there and serves the release. Check the `preview` section of the `CMS` block and `preview.hosts` in `createCMS`, including your dev server's host and port (see Allow previews per host).

Telemetry

Symptom	What to check
No telemetry reaches your collector	Telemetry goes only where the `telemetry` option points, or to `OTEL_EXPORTER_OTLP_ENDPOINT` when the option is left out. Check that it isn't `false` and that the `telemetry` section of the `CMS` block doesn't set `enabled` to `false`. Metrics are sent in batches and errors are sampled, so expect a delay and only a share of errors. More in Telemetry troubleshooting.
Upstream calls missing from telemetry	Only requests made through `createInstrumentedFetch` are measured; check that your client uses it (see Calling APIs).

Problems specific to the hosted Deco CMS, such as a release that hasn't reached a server, are in Publishing without a deploy.