17 — Troubleshooting
Ordered by how often each one actually happens.
The site renders without any styling
Almost always the licence or the Set.
- Licence key and product code entered? Yavi Theme → Licence. Both fields are required — an empty product code fails exactly like a wrong key.
- Is the theme's Set active? Site Management → Sites → Sets must list
yavi-lucerne/full, notyavi-core/full. - Cache flushed?
vendor/bin/typo3 cache:flush. - Domain changed recently? The licence is bound to a host. Open the licence page once and save to re-check for the new domain.
A setting in the backend module has no effect
- Is
config/sites/<id>/settings.yamlwritable? If not, the form saves without error but nothing is stored. - Is it a factor field? Corner rounding (factor) and Button rounding (factor) take a multiplier (
1,0.5,2), not a length.12pxthere is discarded — the value would producecalc(28px * 12px). - Is it an SCSS variable? The four brand colours and the status colours are compiled into the stylesheet. Flush the cache.
- Does the theme override it? A theme's Set wins over core's default; your site setting wins over both — but only when it is actually stored, and a value equal to the default is deliberately not stored.
Changed the navigation variant, nothing happened
Flush the cache. Only the selected variant is compiled into the CSS; without a flush you get the new markup with the old stylesheet.
Backend module shows a field without a label, or a raw LLL: string
A language reference points at a key that does not exist. Check the key in Resources/Private/Language/Backend.xlf. When TYPO3 core renames a label — v14 did rename the palette labels — old references resolve to nothing.
German labels appear in an English backend
The default XLIFF file carries a German source. Fix the source in Backend.xlf and put the German into de.Backend.xlf.
Translation files must be named de.<file>.xlf, not <file>.de.xlf. With the wrong name the file is silently ignored and everything stays English.
Editor's JavaScript in the backend does nothing after an update
The importmap is cache-busted by a hash over the project path and extension versions — but only outside Development context. In Production or a custom context such as Testing/Stage, editing a JavaScript file does not change the ?bust= parameter, and the browser keeps the old module. Flush the cache and reload with a hard refresh (⇧⌘R / Ctrl+F5).
Spacing disappears when a utility class is used
Bootstrap Package's frame carries a negative margin-top. A utility that overrides the frame's padding-top lets that negative margin eat the spacing. Adjust the frame instead of adding another margin.
A background image is not visible
Check whether an ancestor between the frame and the background container became position: relative. The background container is absolutely positioned and attaches to the nearest positioned ancestor; a new one re-parents it away from the element that carries the height.
An animated element sticks out to the right
slide- animations move an element by its own width and become visible the moment they start. Inside the carousel the theme clips this horizontally (overflow-x: clip, with overflow-y: visible so the scroll button below the slide survives). Elsewhere, prefer fade-.
Card items lost their icon fields
The link palette of the card item was overridden. The icon fields live in the Media tab of the card item, not in the link palette.
Fonts are not applied
Self-hosted Google fonts are downloaded on demand and cached under fileadmin/. If the directory is not writable, or the server has no outbound network, the family silently falls back to the stack in Font family.
Diagnosing methodically
# 1. Are the extensions active?
vendor/bin/typo3 extension:list | grep yavi
# 2. Is the compiled stylesheet there?
ls -l typo3temp/assets/bootstrappackage/css/
# 3. What does the page actually deliver?
curl -s https://example.com/ | grep -o 'theme-[a-f0-9]*\.css'
# 4. Rebuild everything
vendor/bin/typo3 cache:flushIf the fourth step fixes it, the problem was cached state — which is worth knowing, because it means the configuration itself is correct.