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

# Installation Issues {#troubleshooting-installation-issues}

Solutions for problems encountered during extension installation, configuration, and setup.

**Table of Contents**

-   [Image Insert Button Not Appearing](https://docs.typo3.org/permalink/netresearch/rte-ckeditor-image:image-insert-button-not-appearing@main)
-   [Extension Installation Problems](https://docs.typo3.org/permalink/netresearch/rte-ckeditor-image:extension-installation-problems@main)
-   [Dependency Conflicts](https://docs.typo3.org/permalink/netresearch/rte-ckeditor-image:dependency-conflicts@main)
-   [Cache-Related Issues](https://docs.typo3.org/permalink/netresearch/rte-ckeditor-image:cache-related-issues@main)
-   [Permission Problems](https://docs.typo3.org/permalink/netresearch/rte-ckeditor-image:permission-problems@main)
-   [Static Template Configuration](https://docs.typo3.org/permalink/netresearch/rte-ckeditor-image:static-template-configuration@main)
-   [Image Processing Configuration](https://docs.typo3.org/permalink/netresearch/rte-ckeditor-image:image-processing-configuration@main)
-   [Debugging Installation](https://docs.typo3.org/permalink/netresearch/rte-ckeditor-image:debugging-installation@main)
-   [Database Issues](https://docs.typo3.org/permalink/netresearch/rte-ckeditor-image:database-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 Insert Button Not Appearing {#troubleshooting-install-image-button-missing}

> [!IMPORTANT]
> This is the **most common issue** after installation. The insert image button is missing
> from the CKEditor toolbar. Follow these checks in order.

### Cause 1: Site Set Dependency Not Added {#cause-1-site-set-dependency-not-added}

The extension requires a **Site Set dependency** in your site configuration.
Without it, the RTE preset is not loaded and the button will not appear.

**Solution:** Add the dependency to your site configuration:

**config/sites/\<your-site>/config.yaml**

```yaml
base: 'https://example.com/'
rootPageId: 1
dependencies:
  - netresearch/rte-ckeditor-image
```

### Cause 2: Bootstrap Package or Theme Extension Overriding the Preset {#cause-2-bootstrap-package-or-theme-extension-overriding-the-preset}

Extensions like `bootstrap_package` set their own `RTE.default.preset` via Site Sets.
If their preset loads **after** ours, it overrides the `rteWithImages` preset.

**Solution:** List `netresearch/rte-ckeditor-image` **after** the theme package
in your site dependencies:

**config/sites/\<your-site>/config.yaml**

```yaml
dependencies:
  - bootstrap-package/full
  - netresearch/rte-ckeditor-image  # Must come AFTER theme packages
```

This ensures our preset loads last and overrides the theme's RTE preset.

> [!NOTE]
> **See also**
>
> [Issue: Insert Image Button Missing with Bootstrap Package or Other Site Sets](https://docs.typo3.org/permalink/netresearch/rte-ckeditor-image:troubleshooting-bootstrap-package-override@main) for a detailed explanation
> of Site Set loading order.

### Cause 3: Custom YAML Preset Missing `insertimage` {#cause-3-custom-yaml-preset-missing-insertimage}

If you use a custom RTE preset YAML file, the `insertimage` toolbar item must be
listed explicitly.

**Solution:** Ensure your custom preset includes the plugin import and toolbar item:

**EXT:my_sitepackage/Configuration/RTE/Custom.yaml**

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

editor:
  config:
    toolbar:
      items:
        - heading
        - '|'
        - bold
        - italic
        - '|'
        - insertimage  # Required for the image button
        - link
```

### Cause 4: Cache Not Cleared After Installation {#cause-4-cache-not-cleared-after-installation}

TYPO3 caches RTE configuration aggressively. After installing the extension or
changing site configuration, caches must be flushed.

**Solution:**

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

Also clear your browser cache and do a hard reload (Ctrl+Shift+R).

**Verification:**

After applying the fix, check that the RTE preset is active:

1.  Go to **Site Management > Page TSconfig**
1.  Search for `RTE.default.preset`
1.  It should show `rteWithImages`

If it shows a different preset (e.g., `bootstrap`, `default`), the Site Set dependency
is not loaded or is being overridden.

---

## Extension Installation Problems {#extension-installation-problems}

### Issue: Extension Not Working After TYPO3 13 Upgrade {#issue-extension-not-working-after-typo3-13-upgrade}

**Symptoms:**

-   Extension installed but not functional
-   Errors about missing classes

**Solution:** Ensure correct version compatibility:

```json
{
  "require": {
    "typo3/cms-core": "^13.4",
    "netresearch/rte-ckeditor-image": "^13.0"
  }
}
```

```bash
composer update
./vendor/bin/typo3 cache:flush
./vendor/bin/typo3 extension:setup
```

> [!WARNING]
> TYPO3 13 requires extension version 13.0.0 or higher for compatibility.

---

## Dependency Conflicts {#dependency-conflicts}

### Issue: Style Drop-Down Dependency Error {#issue-style-drop-down-dependency-error}

**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: JavaScript Dependency Errors {#issue-javascript-dependency-errors}

**Symptoms:**

-   Browser console shows "GeneralHtmlSupport is not defined"
-   Editor doesn't load properly

**Cause:** Extension version < 13.0.0

**Solution:** Update to latest version:

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

---

## Cache-Related Issues {#cache-related-issues}

### Issue: Configuration Changes Not Applied {#issue-configuration-changes-not-applied}

**Symptoms:**

-   RTE configuration changes don't take effect
-   Old behavior persists after updates

**Solution:** Clear all caches:

```bash
# Clear all TYPO3 caches
./vendor/bin/typo3 cache:flush

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

# Clear browser cache and reload
```

> [!TIP]
> Always clear caches after modifying RTE configuration files.

---

### Issue: File References Not Updated {#issue-file-references-not-updated}

**Symptoms:**

-   Image selected but error occurs
-   Empty image inserted
-   "File Not Found" errors

**Solution:** Clear file abstraction layer cache:

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

**Additional Steps:**

1.  Verify file exists in `fileadmin/`
1.  Check file permissions (readable by web server)
1.  Rebuild reference index:

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

---

## Permission Problems {#permission-problems}

### Issue: File Browser Empty or Not Loading {#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
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: Processed Images Directory Not Writable {#issue-processed-images-directory-not-writable}

**Symptoms:**

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

**Solution:** Check directory permissions:

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

# Verify ownership
chown www-data:www-data fileadmin/_processed_/
```

---

## Static Template Configuration {#static-template-configuration}

### Issue: Static Template Not Included {#issue-static-template-not-included}

**Symptoms:**

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

**Solution:**

1.  **Include Static Template:**

    -   Go to **Template** → **Info/Modify**
    -   Edit whole template record
    -   Include `CKEditor Image Support` before Fluid Styled Content
1.  **Verify TypoScript:**

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

> [!WARNING]
> Always include the static template BEFORE Fluid Styled Content for proper rendering.

---

### Issue: Click-to-Enlarge Not Working with sys_template Records (TYPO3 v13) {#issue-click-to-enlarge-not-working-with-sys-template-records-typo3-v13}

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

TYPO3 v13 introduced site sets as a modern alternative to sys_template records.
When sys_template records exist, site sets are bypassed, which affects extensions
that rely on site set dependencies.

**Symptoms:**

-   Images display correctly in frontend
-   Click-to-enlarge functionality doesn't work
-   Data attributes still visible in HTML output (`data-htmlarea-zoom`, `data-htmlarea-file-uid`)
-   Image processing hooks not executed

**Cause:**

In TYPO3 v13, **sys_template records prevent site sets from loading**. Legacy installations
like the Introduction Package use sys_template records instead of modern site sets. When
a sys_template exists on a page, TYPO3 ignores site set dependencies, so the extension's
TypoScript configuration is never loaded.

**Detection:**

Check if your site uses sys_template records:

```sql
SELECT uid, pid, title, include_static_file
FROM sys_template
WHERE deleted=0 AND hidden=0;
```

If records exist and `data-htmlarea-*` attributes appear in frontend HTML, the extension's
TypoScript is not being loaded.

**Solution 1: Manual TypoScript Include (Quick Fix)**

Add TypoScript directly to the sys_template record:

1.  Go to **WEB > Template** module
1.  Select page with sys_template record
1.  Click **Edit the whole template record**
1.  In **Setup** field, add:

```typoscript
# Include RTE CKEditor Image TypoScript
<INCLUDE_TYPOSCRIPT: source="FILE:EXT:rte_ckeditor_image/Configuration/TypoScript/ImageRendering/setup.typoscript">
```

1.  Save template
1.  Clear all caches:

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

**Solution 2: Migrate to Site Sets (Recommended for TYPO3 v13)**

Modern TYPO3 v13 approach:

1.  **Remove sys_template records** from pages (or set them to deleted/hidden)
1.  **Enable site set dependencies** in `config/sites/<site>/config.yaml`:

```yaml
base: 'https://example.com/'
rootPageId: 1
dependencies:
  - typo3/fluid-styled-content
  - netresearch/rte-ckeditor-image
```

1.  **Clear caches:**

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

1.  **Verify in frontend** \- data attributes should be removed and click-to-enlarge should work

**Why This Happens:**

-   **TypoScript must be manually included** via static template or import
-   **sys_template records** control TypoScript for their page tree
-   **Bootstrap Package** in sys_template may clear `lib.parseFunc_RTE` hooks
-   **Load order matters** \- include the extension's TypoScript after theme packages but before Fluid Styled Content

**Verification:**

After applying fix, check frontend HTML:

```html
<!-- Before (BROKEN): -->
<img src="..." data-htmlarea-zoom="true" data-htmlarea-file-uid="2" />

<!-- After (WORKING): -->
<a href="/index.php?eID=tx_cms_showpic&file=2&...">
    <img src="..." />
</a>
```

> [!IMPORTANT]
> sys_template records are legacy. TYPO3 v13 prefers site sets for better
> dependency management and proper load order control. Migrating to site sets
> is recommended for long-term maintainability.

---

### Issue: Insert Image Button Missing with Bootstrap Package or Other Site Sets {#troubleshooting-bootstrap-package-override}

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

Site Set dependency ordering ensures proper override behavior.

**Symptoms:**

-   Extension is installed and active
-   "Insert image" button missing from RTE toolbar
-   Page TSConfig shows `RTE.default.preset = bootstrap` (or another third-party preset)

**Cause:**

Third-party extensions like `bootstrap_package` use **Site Sets** to configure the RTE.
In TYPO3 v13, Site Sets have **higher priority** than extension `page.tsconfig` files.

The loading order is:

1.  Extension `Configuration/page.tsconfig` (our `RTE.default.preset = rteWithImages`)
1.  Site Set configurations (bootstrap's `RTE.default.preset = bootstrap` **overrides ours**)

When your site uses a Site Set dependency like `bootstrap-package/full`, it loads
**after** our extension's page.tsconfig and overrides our RTE preset.

**Detection:**

Check the active RTE preset in Page TSConfig module:

1.  Go to **Site Management** → **Page TSconfig**
1.  Search for `RTE.default.preset`
1.  If it shows `bootstrap` or another preset (not `rteWithImages`), you have this issue

Or check your site configuration:

**config/sites/\<site>/config.yaml**

```yaml
dependencies:
  - bootstrap-package/full  # This overrides our RTE preset!
```

**Solution: Add Site Set Dependency**

Add `netresearch/rte-ckeditor-image` to your site dependencies **after** the overriding
package so our preset loads last:

**config/sites/\<site>/config.yaml**

```yaml
base: 'https://example.com/'
rootPageId: 1
dependencies:
  - bootstrap-package/full
  - netresearch/rte-ckeditor-image  # Must come AFTER bootstrap-package
```

Clear caches after updating:

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

**Why This Works:**

Our Site Set (`netresearch/rte-ckeditor-image`) declares `optionalDependencies` on
bootstrap-package, so when both are listed, ours loads **after** bootstrap and overrides
their RTE preset with `rteWithImages`.

**EXT:rte_ckeditor_image/Configuration/Sets/RteCKEditorImage/config.yaml**

```yaml
name: netresearch/rte-ckeditor-image
label: 'CKEditor Image Support'
optionalDependencies:
  - bootstrap-package/content-elements
  - bootstrap-package/full
```

**Affected Packages:**

This issue affects any extension that sets `RTE.default.preset` via Site Sets:

-   `bootstrap_package` (sets `RTE.default.preset = bootstrap`)
-   Other theme packages with custom RTE configurations
-   Any extension using Site Sets for RTE configuration

**Verification:**

After adding the dependency:

1.  Clear all caches
1.  Go to any content element with an RTE field
1.  Verify the **Insert image** button appears in the toolbar
1.  Check Page TSConfig shows `RTE.default.preset = rteWithImages`

> [!TIP]
> The extension's Site Set is designed to work alongside theme packages.
> Simply adding it to your site dependencies is the correct solution—no
> manual TSConfig overrides needed.

---

## Image Processing Configuration {#image-processing-configuration}

### Issue: ImageMagick/GraphicsMagick Not Configured {#issue-imagemagick-graphicsmagick-not-configured}

**Symptoms:**

-   Original large images displayed instead of processed versions
-   Image processing test fails

**Solution:** Verify image processing configuration:

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

**Test Image Processing:**

```bash
./vendor/bin/typo3 backend:test:imageprocessing
```

---

## Debugging Installation {#debugging-installation}

### Check Extension Installation {#check-extension-installation}

```bash
# Verify extension is installed
composer show netresearch/rte-ckeditor-image

# Check TYPO3 extension list
./vendor/bin/typo3 extension:list
```

### Verify Configuration Loading {#verify-configuration-loading}

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

### Check Browser Console {#check-browser-console}

1.  Open browser DevTools (F12)
1.  Go to Console tab
1.  Look for errors related to:

    -   Plugin loading
    -   Configuration issues
    -   Missing dependencies

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

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

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

---

## Database Issues {#database-issues}

### Issue: Large Database Size {#issue-large-database-size}

**Symptoms:**

-   Database growing rapidly
-   sys_refindex table very large

**Cause:** Excessive soft reference entries

**Solution:** Rebuild reference index:

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

**Check References:**

```sql
-- Find images in RTE content
SELECT uid, bodytext
FROM tt_content
WHERE bodytext LIKE '%data-htmlarea-file-uid%';
```

---

## Related Documentation {#related-documentation}

**Other Troubleshooting Topics:**

-   [Editor Issues](https://docs.typo3.org/permalink/netresearch/rte-ckeditor-image:troubleshooting-editor-issues@main) \- Editor and backend 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
-   [System Architecture](https://docs.typo3.org/permalink/netresearch/rte-ckeditor-image:architecture-overview@main) \- System architecture
-   [Getting Started](https://docs.typo3.org/permalink/netresearch/rte-ckeditor-image:getting-started@main) \- Initial setup

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