Skip to main content
Keel Docs Showcase

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_KEY is 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.local as KEEL_LICENSE_KEY=…. Enable sodium for the web server's PHP too. Then bin/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. Run bin/console cache:clear if 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/keel is older than the bundle's. Studio then hides the tab.
  • Fix: bin/console assets:install public and bin/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.paths is empty, or no path contains {scope}. Keel ignores paths without it. Or scope.options is 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 urls entry and no URL provider. Or published_only is 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 Product when the class name is wrong.

Search misses items

  • Cause: the search index is behind or incomplete. Keel uses it while fewer than search.max_queue changes wait.
  • Fix: rebuild it: bin/console generic-data-index:update:index -r, and check bin/console generic-data-index:status. To stop using the index, set search.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 every cache:clear by itself. See Queue workers after a deploy.
  • Check: bin/console generic-data-index:status shows how many changes still wait. bin/console messenger:stats shows the count in pimcore_generic_data_index_failed (updates that failed three times). Send those again with bin/console messenger:failed:retry --transport=pimcore_generic_data_index_failed, or rebuild the index with bin/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. --check warns 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.yaml only 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.yaml is not valid. The message names the key and the value, for example keel.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.yaml change 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_filesize or post_max_size is lower than uploads.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 (default pimcore_generic_execution_engine).
  • Fix: check that messenger:consume runs and lists that transport, or set bulk.transport to one it does consume, for example pimcore_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:maintenance run. 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_job and keel_bulk_item come from bin/console keel:install-tables (or pimcore:bundle:install KeelBundle); keel:setup --check marks missing tables with ✖. Old jobs are removed by pimcore:maintenance after bulk.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.