---
title: "Editor Issues"
manual: "RTE CKEditor Image"
version: "main"
permalink: "https://docs.typo3.org/permalink/netresearch/rte-ckeditor-image:troubleshooting-editor-issues@main"
source: "Troubleshooting/Editor-Issues.rst"
rendered: "2026-10-01T01:27:51+00:00"
---

# Editor Issues {#troubleshooting-editor-issues}

Solutions for problems encountered in the TYPO3 backend editor and CKEditor functionality.

> [!IMPORTANT]
> **Backend vs Frontend Issues**
>
> The **backend RTE** works automatically after `composer require netresearch/rte-ckeditor-image`.
>
> For **frontend rendering issues**, ensure you've included the TypoScript.
> See [Frontend Rendering](https://docs.typo3.org/permalink/netresearch/rte-ckeditor-image:integration-configuration-frontend-rendering@main).
>
> If you're experiencing backend issues, check:
>
> 1.  Clear caches: `./vendor/bin/typo3 cache:flush`
> 1.  Verify extension is activated
> 1.  Check browser console for JavaScript errors

**Table of Contents**

-   [Image Button Problems](https://docs.typo3.org/permalink/netresearch/rte-ckeditor-image:image-button-problems@main)
-   [Style Dropdown Problems](https://docs.typo3.org/permalink/netresearch/rte-ckeditor-image:style-dropdown-problems@main)
-   [File Browser Issues](https://docs.typo3.org/permalink/netresearch/rte-ckeditor-image:file-browser-issues@main)
-   [Image Dimension Problems](https://docs.typo3.org/permalink/netresearch/rte-ckeditor-image:image-dimension-problems@main)
-   [JavaScript/CKEditor Errors](https://docs.typo3.org/permalink/netresearch/rte-ckeditor-image:javascript-ckeditor-errors@main)
-   [Editor Loading Problems](https://docs.typo3.org/permalink/netresearch/rte-ckeditor-image:editor-loading-problems@main)
-   [Plugin Configuration Issues](https://docs.typo3.org/permalink/netresearch/rte-ckeditor-image:plugin-configuration-issues@main)
-   [Debugging Editor Issues](https://docs.typo3.org/permalink/netresearch/rte-ckeditor-image:debugging-editor-issues@main)
-   [Resolved Issues](https://docs.typo3.org/permalink/netresearch/rte-ckeditor-image:resolved-issues@main)
-   [Known Limitations](https://docs.typo3.org/permalink/netresearch/rte-ckeditor-image:known-limitations@main)
-   [Related Documentation](https://docs.typo3.org/permalink/netresearch/rte-ckeditor-image:related-documentation@main)
-   [Getting Help](https://docs.typo3.org/permalink/netresearch/rte-ckeditor-image:getting-help@main)

## Image Button Problems {#image-button-problems}

### Issue: Image Button Not Visible in Toolbar {#troubleshooting-image-button-missing}

**Symptoms:**

-   Insert image button missing from CKEditor toolbar
-   RTE loads but no image functionality

**Causes:**

1.  Plugin not properly imported in RTE configuration
1.  `removePlugins` includes image plugin
1.  Toolbar configuration missing `insertimage` item

**Solution:**

```yaml
# Configuration/RTE/Default.yaml
imports:
  - { resource: "EXT:rte_ckeditor_image/Configuration/RTE/Plugin.yaml" }

editor:
  config:
    removePlugins: null  # Critical: Don't remove image plugin
    toolbar:
      items:
        - insertimage  # Add to toolbar
```

---

## Style Dropdown Problems {#style-dropdown-problems}

### Issue: Style Drop-Down Not Working with Images {#troubleshooting-style-dropdown}

**Symptoms:**

-   Styles disabled when image selected
-   Style changes not applied to images

**Cause:** Missing `GeneralHtmlSupport` dependency (fixed in v13.0.0+)

**Solution:** Ensure you're using extension version 13.0.0 or higher:

```bash
composer require netresearch/rte-ckeditor-image:^13.0
```

The plugin now requires:

```javascript
static get requires() {
    return ['StyleUtils', 'GeneralHtmlSupport'];  // Both mandatory
}
```

> [!IMPORTANT]
> The `GeneralHtmlSupport` dependency is critical for style functionality in v13.0.0+

---

### Issue: Custom Image Styles Lost After Upgrade {#issue-custom-image-styles-lost-after-upgrade}

**Symptoms:**

-   Custom styles no longer available
-   Style drop-down empty

**Cause:** RTE configuration changed

**Solution:** Re-apply custom styles in RTE configuration:

```yaml
editor:
  config:
    style:
      definitions:
        - name: 'Your Custom Style'
          element: 'img'
          classes: ['your-class']
```

---

## File Browser Issues {#file-browser-issues}

### Issue: File Browser Empty or Not Loading {#troubleshooting-file-browser}

**Symptoms:**

-   Modal opens but shows no files
-   File browser stuck loading

**Causes:**

1.  No file mount configured for backend user
1.  Missing file permissions
1.  Empty fileadmin directory

**Solution:**

```typoscript
# User TSConfig
options.defaultUploadFolder = 1:fileadmin/user_upload/
```

Verify backend user has file mount in:
**Backend** → **User Management** → **Backend Users** → **File Mounts**

---

### Issue: "File Not Found" After Selection {#issue-file-not-found-after-selection}

**Symptoms:**

-   Image selected but error occurs
-   Empty image inserted

**Causes:**

1.  File reference invalid
1.  Storage not accessible
1.  File deleted from filesystem

**Solution:**

1.  Verify file exists in `fileadmin/`
1.  Check file permissions (readable by web server)
1.  Clear file abstraction layer cache:

```bash
./vendor/bin/typo3 cache:flush --group=system
```

---

## Image Dimension Problems {#image-dimension-problems}

### Issue: Magic Image Maximum Dimensions Not Working {#issue-magic-image-maximum-dimensions-not-working}

**Symptoms:**

-   Images not respecting configured maxWidth/maxHeight
-   Large images not being resized

**Cause:** TSConfig settings in custom template extension not loaded (TYPO3 bug #87068)

**Solution:** Add settings to root page config instead:

```typoscript
# In root page TSConfig (not template extension)
RTE.default.buttons.image.options.magic {
    maxWidth = 1920
    maxHeight = 9999
}
```

> [!TIP]
> Place TSConfig settings in root page configuration for proper loading.

---

## JavaScript/CKEditor Errors {#javascript-ckeditor-errors}

### Issue: JavaScript Console Errors {#issue-javascript-console-errors}

**Symptoms:**

-   Browser console shows errors
-   Editor doesn't load properly

#### Common Errors {#common-errors}

##### 1\. "GeneralHtmlSupport is not defined" {#1-generalhtmlsupport-is-not-defined}

**Cause:** Extension version < 13.0.0

**Solution:** Update to latest version:

```bash
composer update netresearch/rte-ckeditor-image
```

##### 2\. "Cannot read property 'typo3image' of undefined" {#2-cannot-read-property-typo3image-of-undefined}

**Cause:** Plugin configuration not loaded

**Solution:** Verify `Configuration/RTE/Plugin.yaml` imported:

```yaml
imports:
  - { resource: "EXT:rte_ckeditor_image/Configuration/RTE/Plugin.yaml" }
```

---

### Issue: Double-Click on Image Does Nothing {#issue-double-click-on-image-does-nothing}

**Symptoms:**

-   Double-clicking image doesn't open dialog
-   Edit functionality not working

**Causes:**

1.  DoubleClickObserver not registered
1.  JavaScript error blocking execution
1.  Image not recognized as typo3image

**Solution:**

1.  Check browser console for JavaScript errors
1.  Verify image has `data-htmlarea-file-uid` attribute
1.  Clear browser cache and reload
1.  Check CKEditor version compatibility (requires CKEditor 5)

---

## Editor Loading Problems {#editor-loading-problems}

### Issue: Editor Not Initializing {#issue-editor-not-initializing}

**Symptoms:**

-   CKEditor doesn't load
-   Textarea remains plain text field

**Causes:**

1.  JavaScript errors preventing initialization
1.  RTE configuration not loaded
1.  Browser cache issues

**Solution:**

1.  Check browser console for errors
1.  Verify RTE preset is enabled:

```yaml
# Configuration/RTE/Default.yaml
imports:
  - { resource: "EXT:rte_ckeditor/Configuration/RTE/Default.yaml" }
  - { resource: "EXT:rte_ckeditor_image/Configuration/RTE/Plugin.yaml" }
```

1.  Clear browser and TYPO3 caches:

```bash
./vendor/bin/typo3 cache:flush
```

1.  Force reload in browser (Ctrl+Shift+R)

---

## Plugin Configuration Issues {#plugin-configuration-issues}

### Issue: Plugin Not Recognized {#issue-plugin-not-recognized}

**Symptoms:**

-   Image plugin functionality missing
-   Console error about undefined plugin

**Cause:** Plugin configuration not properly loaded

**Solution:** Ensure proper import order:

```yaml
# Configuration/RTE/Default.yaml
imports:
  # Base CKEditor configuration first
  - { resource: "EXT:rte_ckeditor/Configuration/RTE/Default.yaml" }
  # Then image plugin
  - { resource: "EXT:rte_ckeditor_image/Configuration/RTE/Plugin.yaml" }

editor:
  config:
    # Ensure plugin is not removed
    removePlugins: null
    toolbar:
      items:
        - insertimage
```

---

## Debugging Editor Issues {#debugging-editor-issues}

### Enable RTE Debugging {#enable-rte-debugging}

```typoscript
# Page TSConfig
RTE.default.showButtons = *
RTE.default.hideButtons =
```

### Check Loaded Configuration {#check-loaded-configuration}

Browser console:

```javascript
// Check if plugin loaded
console.log(CKEDITOR.instances);

// Inspect editor config
const editor = Object.values(CKEDITOR.instances)[0];
console.log(editor.config);
```

### Monitor Network Requests {#monitor-network-requests}

1.  Open browser DevTools
1.  Go to Network tab
1.  Trigger image selection
1.  Check for failed requests to:

    -   `/rte/wizard/selectimage`
    -   Backend image info API

### Inspect DOM Elements {#inspect-dom-elements}

Check if images have required attributes:

```javascript
// In browser console
document.querySelectorAll('img[data-htmlarea-file-uid]');
```

---

## Resolved Issues {#resolved-issues}

### UTF-8 characters in figcaptions {#troubleshooting-utf8-figcaptions}

<!-- TODO: no Markdown rendering for "versionchanged" -->

**Symptoms:**

-   German umlauts (ä, ö, ü, ß) corrupted in figcaptions on the frontend
-   Accented characters (é, ç, ñ) replaced with garbled text
-   Only figcaptions affected, image alt/title attributes rendered correctly

**Cause:** PHP's `DOMDocument::loadHTML()` defaults to ISO-8859-1
encoding, which corrupts multi-byte UTF-8 characters during HTML parsing.

**Status:** Fixed. All `DOMDocument::loadHTML()` calls now prefix the
HTML with `<?xml encoding="UTF-8">` before parsing. No action required.

### Inline linked images with unresolved t3:// URLs {#troubleshooting-inline-link-resolution}

<!-- TODO: no Markdown rendering for "versionchanged" -->

**Symptoms:**

-   Inline linked images show `t3://page?uid=123` as literal text in the
    frontend `href` instead of the resolved URL
-   Links work in the backend but not on the frontend

**Cause:** The `externalBlocks.a` configuration was dead code — the
`<a>` tag was never listed in the `externalBlocks` comma list, so the
per-tag configuration was silently ignored by TYPO3's parseFunc.

**Status:** Fixed. Link resolution now uses `tags.a` with a dedicated
`renderInlineLink()` method in the `ImageRenderingAdapter`. No action
required.

---

## Known Limitations {#troubleshooting-known-limitations}

### Figcaption line breaks {#troubleshooting-figcaption-line-breaks}

**Symptoms:**

-   Pressing Shift+Enter in figcaption does not insert a line break
-   Adding `<br>` in source mode is removed after saving
-   Caption text always appears on a single line

**Cause:** CKEditor 5's `figcaption` content model only supports inline
text — it does not allow `<br>` tags or block-level elements. The editor
strips unsupported elements during content serialization. This is a CKEditor 5
limitation, not a bug in this extension.

**Workaround:** Captions wrap naturally based on the figure container width.
Since version 13.6.0, the `<figure>` element is automatically constrained
to the image width via `max-width`, so captions wrap within the image
boundary without additional CSS. See [Image styles](https://docs.typo3.org/permalink/netresearch/rte-ckeditor-image:examples-image-styles@main) for
details.

> [!NOTE]
> This limitation applies to all CKEditor 5 figcaptions, not just images
> from this extension. See [CKEditor 5 image captions documentation](https://ckeditor.com/docs/ckeditor5/latest/features/images/images-captions.html)
> for details.

---

## Related Documentation {#related-documentation}

**Other Troubleshooting Topics:**

-   [Image Reference Validation](https://docs.typo3.org/permalink/netresearch/rte-ckeditor-image:troubleshooting-image-reference-validation@main) \- Validate and fix broken image references
-   [Installation Issues](https://docs.typo3.org/permalink/netresearch/rte-ckeditor-image:troubleshooting-installation-issues@main) \- Installation and setup problems
-   [Frontend Issues](https://docs.typo3.org/permalink/netresearch/rte-ckeditor-image:troubleshooting-frontend-issues@main) \- Frontend rendering issues
-   [Performance Issues](https://docs.typo3.org/permalink/netresearch/rte-ckeditor-image:troubleshooting-performance-issues@main) \- Performance optimization

**Additional Resources:**

-   [Integration & Configuration](https://docs.typo3.org/permalink/netresearch/rte-ckeditor-image:integration@main) \- Configuration guide
-   [CKEditor Plugin Development](https://docs.typo3.org/permalink/netresearch/rte-ckeditor-image:ckeditor-plugin-development@main) \- CKEditor plugin architecture
-   [RTE Setup](https://docs.typo3.org/permalink/netresearch/rte-ckeditor-image:integration-configuration-rte-setup@main) \- RTE setup and image selection

## Getting Help {#getting-help}

If issues persist after troubleshooting:

1.  **Check GitHub Issues:** [https://github.com/netresearch/t3x-rte_ckeditor_image/issues](https://github.com/netresearch/t3x-rte_ckeditor_image/issues)
1.  **Review Changelog:** Look for breaking changes in CHANGELOG.md
1.  **TYPO3 Slack:** Join [#typo3-cms](https://typo3.slack.com/archives/typo3-cms)
1.  **Stack Overflow:** Tag questions with `typo3` and `ckeditor`

> [!IMPORTANT]
> When reporting issues, include:
>
> -   TYPO3 version
> -   Extension version
> -   PHP version
> -   Browser console errors
> -   RTE configuration (sanitized)
> -   Steps to reproduce