---
title: "Troubleshooting"
manual: "Headless Content Blocks"
version: "main"
permalink: "https://docs.typo3.org/permalink/netzbewegung/nb-headless-content-blocks:troubleshooting@main"
source: "Troubleshooting.rst"
rendered: "2026-09-22T01:35:25+00:00"
---

# Troubleshooting {#troubleshooting}

This page lists known failure modes **when using the extension** — each entry follows **symptom → cause → fix**. Problems with the extension's own test setup are covered in [Testing troubleshooting](https://docs.typo3.org/permalink/netzbewegung/nb-headless-content-blocks:testing-troubleshooting@main); if your case is missing, open an issue.

## A field is `null` in the JSON and the log mentions an unknown type {#a-field-is-null-in-the-json-and-the-log-mentions-an-unknown-type}

**Symptom:** a field renders as `null` and the TYPO3 log contains a debug-level entry about an unconvertible or unknown value type.

**Cause:** the value reached the end of the normalizer chain without any normalizer claiming it. Unconvertible values become `null` **by design** (never break the whole response) — this includes booleans and floats, which do not occur in real Content Block records. Previously such values were dropped silently; now they are visible.

**Fix:** register a [custom normalizer](https://docs.typo3.org/permalink/netzbewegung/nb-headless-content-blocks:register-a-custom-normalizer@main) for the value type. If the field should not be in the response at all, remove it from the Content Block.

## JSON keys are database columns (`tx_myext_field`) instead of identifiers {#json-keys-are-database-columns-tx-myext-field-instead-of-identifiers}

**Symptom:** some keys in `data` are the prefixed column names instead of the Content Block field identifiers (`my_field`).

**Cause:** the column → identifier mapping only covers fields that are **defined in the Content Block's config.yaml**. Columns that TYPO3 or another extension added to the table (but that are not Content Block fields) pass through unmapped — the raw column name is the documented fallback.

**Fix:** none needed if the column is intentional (e.g. `useExistingField` entries are mapped when defined). Otherwise define the field in the Content Block YAML, or drop the column from the output with a [field value transformer](https://docs.typo3.org/permalink/netzbewegung/nb-headless-content-blocks:register-a-field-value-transformer@main) / event listener.

## `thumbnails` are missing on image fields {#troubleshooting-thumbnails-missing}

**Symptom:** `my_image` has `id/alt/title/publicUrl` but no `thumbnails` key, although a `headless.yaml` exists.

**Cause — pick one:**

-   The `headless.yaml` is not directly next to the Content Block's `config.yaml` (wrong folder or wrong file name).
-   The YAML structure is wrong: processing is keyed **by field identifier** (`fields.<identifier>.processing.<variant>`), not by column name.
-   The parsed `headless.yaml` is cached: after changes, clear the TYPO3 cache (`ddev typo3 cache:flush` in DDEV setups).
-   The field is not a File/FileReference field.

**Fix:** correct the file and clear the cache. See [Define image variants](https://docs.typo3.org/permalink/netzbewegung/nb-headless-content-blocks:define-image-variants@main) for the schema and the TypoScript override that wins over `headless.yaml`.

## JSON contains a `__errorMessage` key {#json-contains-a-errormessage-key}

**Symptom:** the block's `data` (or a link object) contains an `__errorMessage` entry instead of the expected value.

**Cause:** a referenced file no longer exists (`FileDoesNotExistException`), or a typolink target could not be resolved (`UnableToLinkException`). In both cases the rest of the response stays intact on purpose — the error is reported in place instead of breaking the page.

**Fix:** repair the record — re-select the file in the Backend, or fix the link target. The message text names the affected record/target.

## Password fields are empty strings {#password-fields-are-empty-strings}

**Symptom:** every `Password` field renders as `""`.

**Cause:** by design — `PasswordBlanker` blanks password values before they reach any headless client. See [Normalizers and transformers](https://docs.typo3.org/permalink/netzbewegung/nb-headless-content-blocks:normalizers-and-transformers@main).

**Fix:** none — expected behavior. Do not send password hashes to the frontend.

## Keys inside `data` are alphabetically sorted {#keys-inside-data-are-alphabetically-sorted}

**Symptom:** field order in the JSON differs from the order in the Content Block YAML.

**Cause:** by design — the output is `ksort`ed. Consumers already rely on the sorted order; it is part of the frozen [JSON contract](https://docs.typo3.org/permalink/netzbewegung/nb-headless-content-blocks:json-contract@main).

**Fix:** none — expected behavior. Sort concerns belong to the frontend.

## Rich text renders without the expected wrapping (`<p>` classes, etc.) {#rich-text-renders-without-the-expected-wrapping-p-classes-etc}

**Symptom:** richtext fields come back as HTML, but without the site's `parseFunc` classes/wrappers.

**Cause:** richtext fields are rendered through `ContentObjectRenderer::parseFunc($value, null, '< lib.parseFunc_RTE')`. The wrapper classes come from *your* TypoScript `lib.parseFunc_RTE`, not from this extension. Since TYPO3 13.2 `lib.parseFunc` is always provided by ext:frontend, but site-specific classes require your site package's setup.

**Fix:** configure `lib.parseFunc_RTE` in your site package (typically via fluid_styled_content's richContentObject or your own setup).

## A block renders `"has no rendering definition!"` instead of JSON {#a-block-renders-has-no-rendering-definition-instead-of-json}

**Symptom:** the block appears in the page JSON, but instead of a `data` object it carries an error text like `Content Element with uid "1" and type "vendor_myblock" has no rendering definition!`.

**Cause:** the block has no TypoScript mapping. EXT:content_blocks auto-generates `tt_content.<ctype> =< lib.contentBlock` only for Content Blocks that ship a frontend template (`templates/frontend.html`). Template-less blocks and custom (non-Content-Block) content elements fall through to `tt_content.default`.

**Fix:** either give the block a `templates/frontend.html` (an empty one is enough — it is not rendered, the JSON output comes from the data processors) or map it yourself in your site package's TypoScript:

```typoscript
tt_content.vendor_myblock =< lib.contentBlock
```

See [How it works](https://docs.typo3.org/permalink/netzbewegung/nb-headless-content-blocks:getting-started@main).

## Container children do not render / render twice {#container-children-do-not-render-render-twice}

**Symptom:** the container's `left`/`right` columns are empty, or the children appear in the normal page content *and* in the column.

**Cause:** the container's TypoScript wiring. `lib.content` must exclude the container column positions, otherwise the children are rendered by the page content query as well.

**Fix:** add the exclusion and map the columns via `nb-container-json` — see [Render containers](https://docs.typo3.org/permalink/netzbewegung/nb-headless-content-blocks:render-containers@main).