Connection Troubleshooting
Sometimes you may run into some problems when you try to connect a new site to Panopticon, or you may “suddenly” get an error, as diagnosed by the Connection Doctor page. In here, we will tell you some of the comment problems and how to troubleshoot them.
Some third party plugins — especially those in the system, content, actionlog, and behaviour folders which are loaded by Joomla! on every request — break the Joomla! API application in subtle, non-obvious ways. For example, they may set the document to HTML instead of JSON, replace the database driver, etc. These extensions are inherently incompatible with Joomla! 4.x and later versions as they break the API application entirely.
Start by disabling one system plugin at a time as long as it's not a plugin which is part of Joomla! itself. Note down each plugin you disable. After disabling each plugin, retry the connection. When the connection succeeds you will know that the problem plugin was the last one you disabled. Remember to re-enable all other plugins you had disabled during this process!
If you have such an extension you will have to contact its developer to get it fixed. You may want to link them to this article from June 2022 which explains what the common problems are, and how to fix them.
Some third party plugins — especially those in the system, content, actionlog, and behaviour folders which are loaded by Joomla! on every request — break the Joomla! frontend output in subtle, non-obvious ways. For example, they may set the document to HTML instead of what is defined in the Joomla! document (JSON, raw, ...), emit PHP notices and warnings, etc. These extensions are inherently incompatible with Joomla! 3.x as they break the way Joomla! is sipposed to work.
Start by disabling one system plugin at a time as long as it's not a plugin which is part of Joomla! itself. Note down each plugin you disable. After disabling each plugin, retry the connection. When the connection succeeds you will know that the problem plugin was the last one you disabled. Remember to re-enable all other plugins you had disabled during this process!
If you have such an extension you will have to contact its developer to get it fixed. You may want to link them to this article from June 2022 which explains what the common problems are, and how to fix them.
You will see an error in the process step "Unauthenticated access (can I even access the API at all?)" with the HTTP Body referencing a plugin, and giving you contact information to its developer. This is really one of the previous two cases and Panopticon's connector was able to find out which plugin causes the problem.
If you have such an extension you will have to contact its developer to get it fixed. You may want to link them to this article from June 2022 which explains what the common problems are, and how to fix them.
We release new versions of the Connector when new PHP and Joomla! versions come out. Keep in mind that both Joomla! and PHP change over time. We typically try to be proactive, releasing new versions a few weeks to a couple of months before a new PHP or Joomla! version is officially released. However, we can't possibly catch all unknown issues all the time.
If the connection to your site ‘suddenly’ broke start troubleshooting by checking if there's an update to the connector available, and if so install it on your site.
It is possible that something you, your host, or a third party did to your site resulted in some core Joomla! files getting removed, or corrupt.
On Joomla! 4.x and later, go to System, Update, Joomla! and click on "Reinstall Joomla! core files". Follow the instructions to refresh Joomla's core files.
On Joomla! 3.x, go to Components, Joomla! Update and click on "Reinstall Joomla! core files". Follow the instructions to refresh Joomla's core files.
Back in February 2023 there was a security issue with the Joomla! API application which was blown out of proportion. This led some people to disable the entire API application, or plugins related to the API application.
If you have put code in your .htaccess file – either directly, or through a third party tool such as Admin Tools Professional – which blocks access to the api directory of your site you need to remove it.
If you have a .htaccess file inside the api directory itself, remove it.
Go to the backend of your site and make sure that the following plugins are enabled, and their access is set to Public:
-
System - Panopticon Troubleshooting Aid(provided by Panopticon's connector). -
Web Services - Panopticon(provided by Panopticon's connector). -
Web Services - Installer(provided by Joomla!). -
API Authentication - Web Services Joomla Token(provided by Joomla!, required for secure, token-based authentication to the Joomla! API). -
User - Joomla API Token(provided by Joomla!, lets you see and manage the API token).
If any of these plugins is disabled, or if its Access is set to anything other than Public, you will run into connection problems with your site. The connector itself will try to detect and report these issues, but there are cases it might fail to identify the problem.
If you have a menu item with the alias api you need to remove, or rename it. Otherwise, it may prevent access to Joomla's API application in your site's api folder.
Please remember that deleting the item is not enough. You will need to empty the menu items trash to completely remove a menu item.
You have recently restored a backup, transferred your site, changed its secret key in the configuration.php file, or reset your API token
In all of those cases, the secret key is changed. Whenever this happens, the API token changes as well. In this case, you need to copy the new token to Panopticon.
Do keep in mind that the Super User has the option to regenerate or disable the token linked with their user account at any time. Do not assume it's unchanged and enabled; check, and double check. The simplest issues are always the most frequent ones.
The token is pretty long and will overflow the textbox it's displayed in, making it tricky to check if you have copied it in its entirety. Moreover, do note that the API Token may end with one or more equal signs (=); when you double-click on the API token these equal signs are not selected. If any characters, even the equals signs, are missing form the token you copied, the token is invalid and triggers an invalid login error on your site.
Joomla 4 and later generate API access tokens per user. Due to the privileged nature of Panopticon's operation on your site, only tokens generated for Super User accounts will work. The corresponding Super User account must be activated (not Blocked). Kindly note that for reasons that have to do with Joomla's security access model, Panopticon cannot possibly know if this is the problem, or if you used the wrong token. As a result, it may not give you the best advice when it detects this kind of error: in both cases the error reported by Joomla! is that you are not allowed to log into the API application with the provided token.
If you are using a security extension other than Admin Tools Professional it might be blocking the requests sent by Panopticon. The same applies for custom .htaccess files, security solutions applied by your host to the entire server (e.g. mod_security2, Immunify360 etc), and various CDN or security services (e.g. CloudFlare, Sucuri, etc).
If you have trouble connecting please check that your server's firewall or any security software installed on or in front of your site is not preventing access to your site. To make it easier for you to create a whitelist record, if necessary, Panopticon prints the public hostname, and public IP address of the server you have installed Panopticon on at the bottom of the page. It also lists the User-Agent HTTP header sent be panopticon (it always starts with panopticon/). Give these three bits of information to the support personnel of the company hosting the site you are tyring to connect to, so they can check whether access is being blocked. Also note that the same thing may happen with site configuration files (e.g. .htaccess and web.config), or third party security extensions.
If you receive a message that you are getting a 403 (Access Denied) error after having tried the wrong token, and you are using Admin Tools Professional, go to your site's administrator backend, Components, Admin Tools for Joomla, Web Application Firewall, Auto Blocked IP Addresses. If you see an address which matches the IP addresses reported by Panopticon OR you see a record with an IPv6 address (the ones with the : in them) at around the same time you tried adding your site: note down the IP address, go to Components, Admin Tools for Joomla, Web Application Firewall, Unblock an IP and post the IP address there, then click on Unblock this IP.
Some hosts use a transparent proxy (usually Squid) to cache requests made from your server to other hosts. Even though the Joomla! API and the Akeeba Panopticon Connector for Joomla! 3 send headers to indicate their contents must not be cached, some hosts misconfigure their servers in a way that causes stale data from a previous request to be delivered, or the request to flat out fail. In this case, you will need to contact your host and ask them to fix their server configuration.
Sometimes you may have chosen to apply password protection to your entire site while you are developing it. Nothing wrong with that, except it won't let you connect to the Joomla! API (Joomla! 4.x or later) or the Panopticon connector plugin (Joomla! 3) which is a requirement for Panopticon to work. The reason you can't directly provide the server username and password to connect to the API is explained in this comment.
On Joomla! 4 you can work around the problem by explicitly allowing access to the URLs starting with api/ and the administrator/components/com_joomlaupdate/extract.php file (Joomla! Update on Joomla! 4.0.4 and later versions). On an Apache web server you can do this with the following code in your .htaccess file:
SetEnvIf Request_URI "^/api/*" pleaseletmein
SetEnvIf Request_URI "^/administrator/components/com_joomlaupdate/extract.php" pleaseletmein
Order allow,deny
Allow from env=pleaseletmein
Satisfy any
Some third party plugins break the WordPress JSON API application in subtle, non-obvious ways. These plugins are inherently incompatible with Wordpress.
Start by disabling one plugin at a time. Note down each plugin you disable. After disabling each plugin, retry the connection. When the connection succeeds you will know that the problem plugin was the last one you disabled. Remember to re-enable all other plugins you had disabled during this process!
If this didn't work, remember that WordPress also has the so-called “must-use” plugins.
If you have such an extension you will have to contact its developer to get it fixed.
We release new versions of the Connector when new PHP and Wordpress versions come out. Keep in mind that both WordPress and PHP change over time. We typically try to be proactive, releasing new versions a few weeks to a couple of months before a new PHP version is officially released, and right after a new WordPress version is released. However, we can't possibly catch all unknown issues all the time.
If the connection to your site ‘suddenly’ broke start troubleshooting by checking if there's an update to the connector available, and if so install it on your site.
It is possible that something you, your host, or a third party did to your site resulted in some core WordPress files getting removed, or corrupt.
Download the ZIP file for your current version of WordPress from the WordPress Releases page. Extract this file on your computer. Upload the contents of the extracted wordpress directory to your site's web root.
WordPress has its own JSON API application – also known as the REST API – served by the /wp-json URL of your site. The Akeeba Panopticon Connector for WordPress uses this JSON API application to communicate with your site.
There are several plugins and direct methods to disable it, e.g. as described here. If you have installed such a plugin, or otherwise have disabled the REST API in WordPress you need to undo that change.
As a sidenote on security: The REST API application DOES NOT pose a security risk on your site. The names, user IDs, and avatars of your site's users should be considered public information on the basis that they are meant to be used for public-facing features such as comments. The list of your published content (what can be accessed through the API without authentication) is also meant to be public information; after all, that's what Google and other search engines index. Those who say there's a security concern either don't know what security means, or they are trying to sell you something that's of no use, and you do not need.
In all of those cases, the API token has changed. You need to copy the new token to Panopticon.
Check that the Panopticon plugin is enabled on your site. Otherwise, Panopticon cannot contact your site.
Make sure you ahve copied the token in its entirety; it's long. Make sure you have not copied any spaces or newlines before or after the token.
If you are using a security extension other than Admin Tools Professional it might be blocking the requests sent by Panopticon. The same applies for custom .htaccess files, security solutions applied by your host to the entire server (e.g. mod_security2, Immunify360 etc), and various CDN or security services (e.g. CloudFlare, Sucuri, etc).
If you have trouble connecting please check that your server's firewall or any security software installed on or in front of your site is not preventing access to your site. To make it easier for you to create a whitelist record, if necessary, Panopticon prints the public hostname, and public IP address of the server you have installed Panopticon on at the bottom of the page. It also lists the User-Agent HTTP header sent be panopticon (it always starts with panopticon/). Give these three bits of information to the support personnel of the company hosting the site you are tyring to connect to, so they can check whether access is being blocked. Also note that the same thing may happen with site configuration files (e.g. .htaccess and web.config), or third party security extensions.
Some hosts use a transparent proxy (usually Squid) to cache requests made from your server to other hosts. Even though the WordPress REST API and the Akeeba Panopticon Connector for WordPress send headers to indicate their contents must not be cached, some hosts misconfigure their servers in a way that causes stale data from a previous request to be delivered, or the request to flat out fail. In this case, you will need to contact your host and ask them to fix their server configuration.
Sometimes you may have chosen to apply password protection to your entire site while you are developing it. Nothing wrong with that, except it won't let you connect to the WordPress REST API which is a requirement for Panopticon to work.
The reason you can't directly provide the server username and password to connect to the API is explained in this comment for Joomla!, and it's the same for WordPress: HTTP Basic Authentication is consumed by the WordPress REST API and would override the Panopticon API Token, causing authentication issues.