Skip to content

Troubleshooting an install

This page is about getting an extension installed and reachable. Once you can open its screen, each extension's own troubleshooting page takes over.

Work down the list. The symptoms look alike from the outside, but the causes are different and the checks are quick.

A blank white page, or you land back on the dashboard

Almost always a missing permission. This is step 3 of installing an extension, and it is the step that gets skipped.

OpenCart does not tell you that you lack permission. It shows you nothing, or returns you to the dashboard, which reads as a broken extension.

Check, in order:

  1. System → Users → User Groups, edit your own group, and confirm the extension's entry is ticked under both Access Permission and Modify Permission. Ticking only one is enough to produce this symptom.
  2. Log out and log back in. Permissions are loaded at sign-in. Until you do, your session still has the old set and nothing appears to have changed.

If both are true and the page is still blank, carry on down this page.

The install said Success, but the extension did nothing

Check your PHP version. On PHP 8.0 or older the extension declines to install, and OpenCart still reports Success. Look in System → Maintenance → Error Logs for a line containing install refused. It names the version you have and the version you need. Requirements explains what to do next.

The extension is not in the Modules list

The upload did not complete, or you are looking at the wrong list.

  • Confirm the Choose the extension type dropdown is set to Modules.
  • Go to Extensions → Installer and check the extension is listed there. If it is not, the upload did not finish; go back to step 1.
  • If it is listed there but not under Modules, the archive is not a module extension, or it did not extract. Delete it from the Installer and upload it again.

The upload fails, or the progress bar stops

A file the store could not accept or could not write.

  • The file was renamed. The name must be exactly as downloaded, ending in .ocmod.zip. Browsers sometimes append (1) to a repeated download, and that is enough to break it. Download it again to a clean folder.
  • The file was unzipped. Upload the .ocmod.zip itself, not its contents.
  • The upload exceeded a server limit. Your host's upload_max_filesize or post_max_size can be set below the archive size. Your host can raise them.
  • The store cannot write to its own directories. OpenCart needs to write while installing. Your host can confirm the store's directory permissions.

The install runs but reports an error

Read the message; it usually names the problem. Two are common:

  • A file already exists. A previous version, or a partial install, is still in place. Delete the extension from Extensions → Installer and upload again.
  • A database error. The store's database user may lack permission to create tables. Your host can grant it.

If the message is not one of these, ask for help and include the message text exactly as shown.

The screen opens but looks wrong or unstyled

Usually a stale cache after an upload.

  • OpenCart caches its compiled templates. Extensions → Modifications has a refresh button; use it, then reload the page.
  • Reload with your browser's cache bypassed (Ctrl+F5, or Cmd+Shift+R on a Mac).
  • If your store runs behind a CDN or a caching plugin, clear that too.

A correct credential is still refused with 401

Only for an extension that answers an HTTP API. If the credential is right, the API user is enabled, its IP list has the calling server's address on it and the switch on the extension's settings screen is on, and every call still comes back 401, the likeliest cause is your hosting rather than anything you configured.

The Authorization header is being removed before the store sees it. Some Apache and CGI/FastCGI setups drop it, and PHP never receives it. The extension looks for it in four places, so this is uncommon. When all four are empty, though, a correct credential is indistinguishable from an absent one, and the API's answer is deliberately the same either way.

Confirm it, in this order:

  1. Read your Kyvero log, at System → Maintenance → Error Logs, in the kyvero.log tab. The API writes the real reason there, one line per refusal. The response never carries it, because a message that distinguished "no credential" from "wrong credential" would tell an attacker which usernames exist. A line saying no credential was presented, for a call you know sent one, is the confirmation. The store's own error log is the tab beside it, and is where a call that failed outright leaves its full block. See what Kyvero extensions log.
  2. Check the API switch is on for the extension, on its settings screen under Extensions → Modules. Its API panel shows the base URL, the versions answered and a warning if no API user is enabled or none has an IP address. Note that this switch is independent of the extension's own status: the API answers whether or not the extension itself is switched on.
  3. Ask your host to pass the header through. On Apache with PHP as CGI or FastCGI, this is usually one line in .htaccess:

apache RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}]

Your host can confirm whether their configuration strips it and apply the fix; it is a server setting, not a store setting, and nothing in OpenCart can change it.

Rule out two neighbouring causes while you are here. The call must be over HTTPS: the API answers 426 to anything else, and will not read a credential sent in the clear. And the API user's IP list must not be empty: a user with no addresses on it is refused every time, which looks exactly like a wrong password.

Something changed after an update

Read the extension's changelog page first. Behaviour changes are listed there in plain terms, and what looks like a fault is sometimes a documented change.

Your own wording shows & where you typed &

Wording you wrote in an extension's Wording boxes — and a few other text settings, such as a return address or crawl rules — used to be stored with OpenCart's form encoding still on it, and each Save added another layer. So text saved before the release that fixed this can read &, & or " in the box, in mails and on your shop, wherever you typed & or ".

Retype it once: clear the affected text, type it again as you mean it, and press Save. From then on it is stored exactly as typed and stays that way however often you save. Nothing repairs it for you, because a repair could not tell those layers from an & you typed on purpose.

Still stuck

Get in touch. The support page lists what to include so that the first reply is an answer rather than a request for details.