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

# Frontend Issues {#troubleshooting-frontend-issues}

Solutions for problems with image display and rendering in the frontend.

**Table of Contents**

-   [Image Display Problems](https://docs.typo3.org/permalink/netresearch/rte-ckeditor-image:image-display-problems@main)
-   [Broken Links and References](https://docs.typo3.org/permalink/netresearch/rte-ckeditor-image:broken-links-and-references@main)
-   [Dimension Problems](https://docs.typo3.org/permalink/netresearch/rte-ckeditor-image:dimension-problems@main)
-   [Style and Class Problems](https://docs.typo3.org/permalink/netresearch/rte-ckeditor-image:style-and-class-problems@main)
-   [Link Rendering Problems](https://docs.typo3.org/permalink/netresearch/rte-ckeditor-image:link-rendering-problems@main)
-   [Responsive Image Issues](https://docs.typo3.org/permalink/netresearch/rte-ckeditor-image:responsive-image-issues@main)
-   [Caching Issues](https://docs.typo3.org/permalink/netresearch/rte-ckeditor-image:caching-issues@main)
-   [Debugging Frontend Issues](https://docs.typo3.org/permalink/netresearch/rte-ckeditor-image:debugging-frontend-issues@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 Display Problems {#troubleshooting-frontend-rendering}

### Issue: Images Not Appearing in Frontend {#issue-images-not-appearing-in-frontend}

**Symptoms:**

-   Images visible in backend RTE
-   Images missing in frontend output

**Causes:**

1.  TypoScript not included (most common)
1.  Cached content
1.  Custom TypoScript overriding extension configuration

**Solution:**

1.  **Include TypoScript (required):**

    The extension requires manual TypoScript inclusion for frontend rendering:

    **Option A: Static Template**

    1.  Go to **WEB > Template** module
    1.  Select your root page, edit the template
    1.  In **Includes** tab, add: **CKEditor Image Support**

    **Option B: Direct Import**

    ```typoscript
    @import 'EXT:rte_ckeditor_image/Configuration/TypoScript/ImageRendering/setup.typoscript'
    ```
1.  **Clear Caches:**

    ```bash
    ./vendor/bin/typo3 cache:flush
    ```
1.  **Check for TypoScript conflicts:**

    If you have custom `lib.parseFunc_RTE` configuration, ensure it doesn't override the image rendering hooks.

> [!IMPORTANT]
> TypoScript must be manually included. See [Frontend Rendering](https://docs.typo3.org/permalink/netresearch/rte-ckeditor-image:integration-configuration-frontend-rendering@main) for details.

---

### Issue: Processed Images Not Generated {#issue-processed-images-not-generated}

**Symptoms:**

-   Original large images displayed
-   No `_processed_/` directory created
-   Slow page load due to large images

**Causes:**

1.  Image processing disabled
1.  ImageMagick/GraphicsMagick not configured
1.  File permissions issue

**Solution:**

1.  **Verify Image Processing Configuration:**

```php
// LocalConfiguration.php
$GLOBALS['TYPO3_CONF_VARS']['GFX'] = [
    'processor' => 'ImageMagick',  // or 'GraphicsMagick'
    'processor_path' => '/usr/bin/',
    'processor_enabled' => true,
];
```

1.  **Test Image Processing:**

```bash
# TYPO3 CLI
./vendor/bin/typo3 backend:test:imageprocessing
```

1.  **Check Directory Permissions:**

```bash
# Ensure _processed_/ is writable
chmod 775 fileadmin/_processed_/
```

1.  **Check Processed Files:**

```bash
ls -la fileadmin/_processed_/
```

---

## Broken Links and References {#broken-links-and-references}

### Issue: Broken Image Links {#issue-broken-image-links}

**Symptoms:**

-   Broken image icon displayed
-   404 errors in browser console
-   Missing image files

**Causes:**

1.  File moved or deleted
1.  Invalid file reference
1.  Storage configuration changed

**Solution:**

1.  **Run the image reference validator** (recommended):

```bash
# Dry-run: detect broken references
./vendor/bin/typo3 rte_ckeditor_image:validate

# Apply fixes automatically
./vendor/bin/typo3 rte_ckeditor_image:validate --fix
```

See [Image Reference Validation](https://docs.typo3.org/permalink/netresearch/rte-ckeditor-image:troubleshooting-image-reference-validation@main) for full details, including
the Upgrade Wizard alternative.

1.  **Rebuild Reference Index** (required before validation on fresh installs):

```bash
./vendor/bin/typo3 referenceindex:update
```

1.  **Clear File Caches:**

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

---

### Issue: Wrong Image Path in Output {#issue-wrong-image-path-in-output}

**Symptoms:**

-   Image `src` points to the wrong location
-   Image renders correctly at the page root but breaks on sub-pages
-   Missing site path (`/~user/`, `/sub/`) in rendered URLs

**Background:** The extension stores RTE image `src` in canonical
site-root-relative form (`/fileadmin/...`, leading slash). TYPO3 v12+ does
**not** emit `<base href>`, so a slashless `fileadmin/...` value would
resolve against the current page URL in the browser and break on every
non-root page. The validator (see
[Image Reference Validation](https://docs.typo3.org/permalink/netresearch/rte-ckeditor-image:troubleshooting-image-reference-validation@main)) detects and repairs
slashless `src` to the leading-slash form.

**Solution for subpath installs** (TYPO3 served from `/subsite/`,
`/~user/`, or any path other than `/`):

```typoscript
# Prepend the subpath to every leading-slash path at render time.
# This is what makes "/fileadmin/x.jpg" resolve as
# "/subsite/fileadmin/x.jpg" in the rendered HTML.
config.absRefPrefix = /subsite/
```

Use the actual subpath from your site configuration's `base` URL.
`/~user/` (Apache UserDir) and `/subsite/` (alias / docroot subdir)
both work the same way. For site-root installs no TypoScript change
is required — `config.absRefPrefix = /` (the safe default) is
enough.

> [!NOTE]
> `config.baseURL` was deprecated and removed. Modern TYPO3 uses the
> `config/sites/<identifier>/config.yaml` `base` key for the
> canonical site URL; it does **not** emit a `<base href>` tag.

---

## Dimension Problems {#dimension-problems}

### Issue: Images Display at Wrong Size {#issue-images-display-at-wrong-size}

**Symptoms:**

-   Images too large or too small
-   Dimensions not respected
-   Responsive behavior broken

**Causes:**

1.  CSS conflicts
1.  Missing width/height attributes
1.  Responsive image configuration issues

**Solution:**

1.  **Check Generated HTML:**

```html
<!-- Should include width and height -->
<img src="..." width="800" height="600" />
```

1.  **Verify CSS:**

```css
/* Ensure images are responsive */
.rte img {
    max-width: 100%;
    height: auto;
}
```

1.  **Check TypoScript Configuration:**

```typoscript
lib.parseFunc_RTE.tags.img {
    current = 1
    preUserFunc = Netresearch\RteCKEditorImage\Controller\ImageRenderingAdapter->renderImageAttributes
}
```

---

### Issue: Image Dimensions Not Preserved {#issue-image-dimensions-not-preserved}

**Symptoms:**

-   Aspect ratio distorted
-   Images stretched or squashed

**Cause:** Missing or incorrect dimension attributes

**Solution:**

Ensure both width and height are rendered:

```typoscript
lib.parseFunc_RTE.tags.img {
    current = 1
    preUserFunc = Netresearch\RteCKEditorImage\Controller\ImageRenderingAdapter->renderImageAttributes
    stdWrap {
        wrap = <div class="rte-image">|</div>
    }
}
```

---

## Style and Class Problems {#style-and-class-problems}

### Issue: CSS Classes Not Applied {#issue-css-classes-not-applied}

**Symptoms:**

-   Custom classes missing from output
-   Styles not visible in frontend
-   Classes work in backend but not frontend

**Cause:** HTMLparser configuration stripping classes

**Solution:**

```typoscript
lib.parseFunc_RTE.nonTypoTagStdWrap.HTMLparser {
    keepNonMatchedTags = 1
    tags.img {
        allowedAttribs = class,src,alt,title,width,height
        fixAttrib.class.list = your-allowed-classes
    }
}
```

---

### Issue: Data Attributes Visible in Frontend {#issue-data-attributes-visible-in-frontend}

**Symptoms:**

-   `data-htmlarea-file-uid` visible in HTML
-   Internal attributes exposed

**Cause:** HTMLparser configuration missing

**Solution:**

```typoscript
lib.parseFunc_RTE.nonTypoTagStdWrap.HTMLparser.tags.img.fixAttrib {
    data-htmlarea-file-uid.unset = 1
    data-htmlarea-file-table.unset = 1
    # Keep zoom attributes for popup/lightbox rendering
    # data-htmlarea-zoom.unset = 1
    data-title-override.unset = 1
    data-alt-override.unset = 1
}
```

> [!NOTE]
> Internal data attributes should always be removed in frontend rendering.

---

## Link Rendering Problems {#link-rendering-problems}

### Issue: Image Links Not Working {#issue-image-links-not-working}

**Symptoms:**

-   Clickable images don't work
-   Links stripped from output
-   JavaScript conflicts

**Cause:** Link processing configuration

**Solution:**

```typoscript
lib.parseFunc_RTE {
    tags.a = TEXT
    tags.a {
        current = 1
        typolink {
            parameter.data = parameters:href
            title.data = parameters:title
            ATagParams.data = parameters:allParams
        }
    }
}
```

---

### Issue: Lightbox/Zoom Not Working {#issue-lightbox-zoom-not-working}

> [!IMPORTANT]
> **This extension provides zoom markup only, not JavaScript.**
>
> When an editor selects "Enlarge" in the image dialog, the extension outputs an
> `<a>` link wrapping the `<img>` that points to the full-size image. It does
> **not** include any JavaScript lightbox library. You must provide one yourself
> or enable the built-in TYPO3 popup.

**Symptoms:**

-   Clicking an image with zoom enabled does nothing or navigates away
-   `data-htmlarea-zoom` attribute present in HTML but no lightbox appears
-   Image opens in a new browser window instead of a lightbox overlay

**Solution for fluid_styled_content users:**

If you use `fluid_styled_content`, enable the built-in lightbox via TypoScript constants:

```typoscript
styles.content.textmedia.linkWrap.lightboxEnabled = 1
```

This activates TYPO3's built-in popup window for enlarged images.

**Solution for custom setups (minimal lightbox):**

If you do not use `fluid_styled_content` or want a modern lightbox overlay,
include a lightweight JavaScript snippet in your site package:

**Minimal lightbox initialization**

```javascript
document.addEventListener('DOMContentLoaded', function () {
    document.querySelectorAll('a[data-popup="true"]').forEach(function (link) {
        link.addEventListener('click', function (e) {
            e.preventDefault();
            var overlay = document.createElement('div');
            overlay.style.cssText = 'position:fixed;inset:0;background:rgba(0,0,0,.8);'
                + 'display:flex;align-items:center;justify-content:center;z-index:9999;cursor:pointer;';
            var img = document.createElement('img');
            img.src = link.href;
            img.style.cssText = 'max-width:90vw;max-height:90vh;';
            overlay.appendChild(img);
            overlay.addEventListener('click', function () { overlay.remove(); });
            document.body.appendChild(overlay);
        });
    });
});
```

For production use, consider a proper lightbox library such as
[GLightbox](https://github.com/biati-digital/glightbox),
[PhotoSwipe](https://photoswipe.com/), or
[Fancybox](https://fancyapps.com/fancybox/).

> [!NOTE]
> **See also**
>
> [Frontend Rendering](https://docs.typo3.org/permalink/netresearch/rte-ckeditor-image:integration-configuration-frontend-rendering@main) for the full lightbox/popup
> TypoScript configuration reference.

---

### Issue: Unexpected `rel="noreferrer"` on External Linked Images {#issue-unexpected-rel-noreferrer-on-external-linked-images}

**Symptoms:**

-   External linked images (e.g. `<a href="https://example.com" target="_blank">`)
    render with `rel="noreferrer"` even though the editor did not set it
-   Internal links (`/page` or `t3://page?uid=42`) do **not** receive the
    attribute

**Cause:** This is intentional behaviour added in [#799](https://github.com/netresearch/t3x-rte_ckeditor_image/issues/799).
The Fluid `Link.html` partial used for figure-wrapped linked images
mirrors TYPO3 typolink security semantics — it appends `rel="noreferrer"`
when the target opens a new browsing context **and** the URL is external
(absolute `http(s)` or protocol-relative). Pre-existing rel tokens from
the source `<a>` (such as `nofollow` or `noopener`) are preserved.

**Solution:** No action required. To suppress the attribute (not
recommended), remove `target="_blank"` from the link or use an internal
URL. See [External link security (rel="noreferrer")](https://docs.typo3.org/permalink/netresearch/rte-ckeditor-image:integration-security-rel@main) for the full rule and rationale.

---

## Responsive Image Issues {#responsive-image-issues}

### Issue: Images Not Responsive {#issue-images-not-responsive}

**Symptoms:**

-   Images overflow container on mobile
-   Fixed width prevents scaling
-   No srcset generated

**Cause:** Missing responsive configuration

**Solution:**

```css
/* Basic responsive images */
.rte img {
    max-width: 100%;
    height: auto;
    display: block;
}
```

For advanced responsive images with srcset, configure image processing:

```typoscript
lib.parseFunc_RTE.tags.img {
    current = 1
    preUserFunc = Netresearch\RteCKEditorImage\Controller\ImageRenderingAdapter->renderImageAttributes
}
```

---

## Caching Issues {#caching-issues}

### Issue: Old Images Still Displayed {#issue-old-images-still-displayed}

**Symptoms:**

-   Updated images not showing
-   Old version cached
-   Changes visible in backend but not frontend

**Solution:**

1.  **Clear TYPO3 Caches:**

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

1.  **Clear Browser Cache:**

    -   Hard reload: Ctrl+Shift+R (Windows/Linux)
    -   Hard reload: Cmd+Shift+R (Mac)
1.  **Clear Processed Images:**

```bash
# Remove all processed images
rm -rf fileadmin/_processed_/*
```

1.  **Verify Cache Configuration:**

```typoscript
config {
    sendCacheHeaders = 1
    cache_period = 86400
}
```

---

## Debugging Frontend Issues {#debugging-frontend-issues}

### Check Generated HTML {#check-generated-html}

View page source and inspect image markup:

```html
<!-- Expected output -->
<img src="fileadmin/_processed_/.../image.jpg"
     alt="Description"
     width="800"
     height="600"
     class="your-class" />
```

### Verify TypoScript Processing {#verify-typoscript-processing}

```typoscript
# Enable TypoScript debugging
config {
    debug = 1
    admPanel = 1
}
```

### Check Browser Network Tab {#check-browser-network-tab}

1.  Open DevTools (F12)
1.  Go to Network tab
1.  Filter by images
1.  Check for:

    -   404 errors
    -   Slow loading
    -   Wrong paths

### Inspect CSS {#inspect-css}

```css
/* Check for conflicts */
.rte img {
    /* Ensure no display:none or visibility:hidden */
}
```

### Monitor Console Errors {#monitor-console-errors}

Look for JavaScript errors that might affect image rendering:

```javascript
// Common issues
- Failed to load resource
- CORS errors
- JavaScript blocking rendering
```

---

## 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
-   [Editor Issues](https://docs.typo3.org/permalink/netresearch/rte-ckeditor-image:troubleshooting-editor-issues@main) \- Editor and backend problems
-   [Performance Issues](https://docs.typo3.org/permalink/netresearch/rte-ckeditor-image:troubleshooting-performance-issues@main) \- Performance optimization

**Additional Resources:**

-   [Frontend Rendering](https://docs.typo3.org/permalink/netresearch/rte-ckeditor-image:integration-configuration-frontend-rendering@main) \- TypoScript configuration
-   [System Architecture](https://docs.typo3.org/permalink/netresearch/rte-ckeditor-image:architecture-system-components@main) \- Rendering pipeline details
-   [Frontend Rendering](https://docs.typo3.org/permalink/netresearch/rte-ckeditor-image:integration-configuration-frontend-rendering@main) \- Frontend features

## 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
> -   Browser and version
> -   Generated HTML (view source)
> -   TypoScript configuration
> -   Browser console errors
> -   Network tab screenshots