Troubleshooting
Start with bin/console keel:setup --check. It finds most install problems and prints the fix. Each entry below is: symptom → cause → fix, with the --check line that shows it.
"License required"
The Keel tab opens, but shows License required and nothing works.
- Cause:
KEEL_LICENSE_KEYis missing, cut off, has quotes or spaces, or the PHP extension sodium is missing (signed keys need it). - Fix: put the whole key in
.env.localasKEEL_LICENSE_KEY=…. Enable sodium for the web server's PHP too. Thenbin/console cache:clear. - --check:
✖ No licence key: Keel stays locked,✖ The licence key is not valid, or✖ PHP extension sodium is missing.
Keys that do not start with KEEL1. are no longer accepted: ask for a signed key.
"License expired"
The Keel tab opens, but shows License expired. The website keeps running.
- Cause: the key's end date and the 14 days of grace after it have passed.
- Fix: put a renewed key in
KEEL_LICENSE_KEY. Runbin/console cache:clearif the environment variables are cached, then reload the admin. See When a key expires. - --check:
✖ The licence expired on 2027-03-31 and its 14 days of grace are over: Keel is locked, the website keeps running.
The Keel tab is missing in Studio after an update
- Cause: the Studio build in
public/bundles/keelis older than the bundle's. Studio then hides the tab. - Fix:
bin/console assets:install publicandbin/console cache:clear, then reload the browser. - --check:
✖ The installed Studio build is older than the bundle's: Studio hides the Keel tab.
If --check also says the routes sit under the wrong path, config/routes/keel.yaml imports the classic admin's file: use @KeelBundle/config/routes_studio.yaml.
The switcher does not show
- Cause:
scope.pathsis empty, or no path contains{scope}. Keel ignores paths without it. Orscope.optionsis empty. - Fix: write the paths with
{scope}where the option's folder is:paths: ['/Tours/{scope}/']. See Header switcher. - --check:
! keel.scope.paths: /Tours/ has no {scope}, so the switcher stays off.
"View on website" is missing
- Cause: Keel does not know the item's page. The class has no link generator, no
urlsentry and no URL provider. Orpublished_onlyis on and the item is not published. Or a placeholder in the path has no value for this item (for example an empty slug). - Fix: add the class to
urls(Website pages) and check that the fields in the path are filled. - --check:
! keel.urls.Product: there is no class Productwhen the class name is wrong.
Search misses items
- Cause: the search index is behind or incomplete. Keel uses it while fewer than
search.max_queuechanges wait. - Fix: rebuild it:
bin/console generic-data-index:update:index -r, and checkbin/console generic-data-index:status. To stop using the index, setsearch.index: off. See Search. - --check: shows whether the index is used:
✔ List search uses Pimcore's search index (Generic Data Index).
Search misses new items after a deploy or cache clear
- Cause: a queue worker is still running on the old cache, so the search index updates fail. The worker log
shows errors like
Failed opening required '…/var/cache/prod/Container…'. - Fix:
bin/console messenger:stop-workers. Supervisord starts the workers again; the waiting updates are then indexed. Keel sends this signal after everycache:clearby itself. See Queue workers after a deploy. - Check:
bin/console generic-data-index:statusshows how many changes still wait.bin/console messenger:statsshows the count inpimcore_generic_data_index_failed(updates that failed three times). Send those again withbin/console messenger:failed:retry --transport=pimcore_generic_data_index_failed, or rebuild the index withbin/console generic-data-index:update:index -r.
The status tabs do not show
The list has status chips, but no Open / Closed tabs.
- Cause: no status of the field counts as closed. Keel only knows built-in words such as done, zatvoreno, sold, rejected.
- Fix: add your word with
statuses.words.closed(Statuses), or let an admin tick Counts as closed in Customize → Statuses. - No chips at all? The list has no status field: set
collections.<list-key>.status_field, or pick one in Customize.--checkwarns when the field is not a select field:! keel.collections.enquiry.status_field: Enquiry.status is an input field, not a select field.
Keel page check says "could not be checked"
- Cause: Keel could not get the page from the server (a template error, or no answer within about 30 s), or the page did not finish loading within
page_check.timeout_s(default 20 s), or a script on the page never finishes. - Fix: open the page on the website or in Pimcore's preview to see the error or how slow it is. Raise
page_check.timeout_s(up to 120). See Keel page check. - Partly checked is something else: the check runs in an isolated copy of the page, under the admin's Content Security Policy. Pimcore Studio's policy blocks the page's inline scripts, and scripts, fonts and frames from other sites are never loaded. The report says what was left out. Google's numbers may differ; use Open in PageSpeed Insights for those.
A keel.yaml change has no effect
- Cause 1: the cache. Symfony reads
keel.yamlonly when the cache is built. - Fix:
bin/console cache:clear. - Cause 2: Customize overrides it. Colours, statuses and assignments chosen in Customize win over
keel.yaml. - Fix: in Customize, use Reset to automatic (all of Customize), the Project theme preset (colours only), or the Statuses step's own Reset to automatic (one list).
- Cause 3: the browser remembers the user's own choice (language, rows per page). That is on purpose; the user can change it.
cache:clear fails with a keel. message
- Cause: a value in
keel.yamlis not valid. The message names the key and the value, for examplekeel.lists.page_size: 25 is not one of page_sizes (10, 20, 50, 100, 200). - Fix: look the key up in the keel.yaml reference and correct it.
cache:clear runs out of memory
- Cause: with debug on (development containers), building the cache after a
keel.yamlchange can need more than 256 MB. - Fix:
php -d memory_limit=512M bin/console cache:clear. - --check:
! PHP CLI memory_limit is 256 MB: cache:clear (debug on) may need more.
Uploads fail above a certain size
- Cause: PHP's
upload_max_filesizeorpost_max_sizeis lower thanuploads.max_mb. PHP refuses the file before Keel sees it. - Fix: raise both PHP values for the web server (and the CLI), or lower
uploads.max_mb. See Images and uploads. - --check:
! PHP (CLI) allows uploads up to 8 MB, keel.yaml uploads.max_mb is 100. It reads the CLI's PHP settings; the web server's can differ.
A bulk job says "Waiting for the background worker…"
- Why: bulk jobs of more than 20 items are worked through by Pimcore's queue worker. It is down, or it does not consume
the transport in
bulk.transport(defaultpimcore_generic_execution_engine). - Fix: check that
messenger:consumeruns and lists that transport, or setbulk.transportto one it does consume, for examplepimcore_core. Keep the bulk transport last on the command: Symfony serves transports in that order, so the search index and scheduled tasks stay ahead of a long job. Nothing is lost while it waits; the job starts when the worker is back. - After a crash: a job whose worker died goes on by itself after about 2 minutes while someone has Keel open,
otherwise with the next
pimcore:maintenancerun. The item in hand runs again. An item that takes the worker down twice is reported as failed, and the job goes on. - Tables:
keel_bulk_jobandkeel_bulk_itemcome frombin/console keel:install-tables(orpimcore:bundle:install KeelBundle);keel:setup --checkmarks missing tables with ✖. Old jobs are removed bypimcore:maintenanceafterbulk.keep_days.
A screen says it could not be loaded
Lists, Pages, assets, the overview's cards, the item, page and file panels and the Setup screens keep their title when their data cannot be loaded, and show a short message with Retry. A list that fails after it had rows keeps them and shows the message above them. If Retry keeps failing, look at Pimcore's log for the request that failed.
A long export never finishes, or Download is missing
An export of more than export.direct_rows rows (2,000) is written by the queue worker, like a bulk job: see the
section above. The file is kept in Pimcore's temp storage (folder keel-jobs/) for export.keep_hours (72): with more
than one machine that storage must be shared by the web nodes and the worker, or the download is not found.