Editor Issues 

Issue: Image Button Not Visible in Toolbar 

Symptoms:

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

Causes:

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

Solution:

# 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

Issue: Style Drop-Down Not Working with Images 

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:

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

The plugin now requires:

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

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:

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

Issue: File Browser Empty or Not Loading 

Symptoms:

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

Causes:

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

Solution:

# 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 

Symptoms:

• Image selected but error occurs
• Empty image inserted

Causes:

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

Solution:

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

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

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:

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

Issue: JavaScript Console Errors 

Symptoms:

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

composer update netresearch/rte-ckeditor-image

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

Issue: Double-Click on Image Does Nothing 

Symptoms:

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

Causes:

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

Solution:

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

Issue: Editor Not Initializing 

Symptoms:

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

Causes:

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

Solution:

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

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

3. Clear browser and TYPO3 caches:

./vendor/bin/typo3 cache:flush

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

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:

# 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

Enable RTE Debugging 

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

Check Loaded Configuration 

Browser console:

// 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 

1. Open browser DevTools
2. Go to Network tab
3. Trigger image selection

4. Check for failed requests to:

   • /rte/wizard/selectimage
   • Backend image info API

Inspect DOM Elements 

Check if images have required attributes:

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

UTF-8 characters in figcaptions 

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 

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.

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 for details.