Troubleshooting

Unable to install the Probe

We strongly recommend the use of Blackfire repositories to install the Probe.

If you ever experience difficulties while installing or running the Probe with our repositories, you can install it manually by following the manual installation guide in the Probe installation section.

Unable to Install the Agent

We strongly recommend the use of package repositories to install the Agent.

If you ever experience difficulties while installing or running the Agent with our repositories, you can install it manually by following the manual installation guide in the Agent installation section.

Probe installation failure when using cPanel

When using cPanel, please follow the specific cPanel documentation.

Are You Authorized to Profile this Page? Probe Not Found or Invalid signature.

This is the most common issue when installing the Blackfire stack as a result of Blackfire security principles: the probe does not expose anything if you are not allowed to profile, misconfigured it or even forgot to install it.

Therefore this issue can not be diagnosed automatically.

Note

Magento Cloud and Platform.sh users benefit from a special configuration. If you use one of those platforms, please follow the dedicated troubleshooting documentation on their documentation sites:

In any other case, if this issue occurs, please follow these steps:

  1. Check versions

    Ensure you're using the latest Agent, Probe and Companion. Check this page that will tell you if they're outdated.

  2. Check configuration

    Ensure that you properly configured your Blackfire server credentials via blackfire-agent -register. You can display the current configuration with blackfire-agent -d. Ensure that you have restarted your agent after any configuration change. Check how to do that in the documentation for your platform.

  3. Check logs

    If it still does not work, look for any error messages in the logs (see below for paths).

  4. Check the Blackfire probe is properly installed/enabled.

    You can use a simple phpinfo() script in a web context and look for Blackfire configuration.

  5. Adjust cache, proxy or CDN configuration

    If you have a reverse proxy, cache, or content delivery network (CDN) in front of your application, you will want to bypass it when profiling with Blackfire.

  6. Check the page you try to profile is served by PHP.

    For example profiling a web server directory listing won't work. The same applies for single page web-app as files will probably be served directly by the web server. In this last case, you probably want to profile XHR requests instead.

  7. Contact our support

    Collect logs and contact our support.

Agent's Log Contains Error dial tcp: i/o timeout

This error occurs when a timeout happens between the Agent and the Blackire.io server. If you encounter this issue, you can increase the timeout of the Agent by appending the following line to the Agent configuration:

1
timeout=30s

I Can't Find a Solution on this Page

Please give us feedback

If you can't find a solution to your problem, please contact us. Please include the following information in your issue:

  • Your platform (e.g. OSX x64, Debian wheezy x86, Ubuntu Precise x64, etc...)
  • The output of php -v command.
  • The output of php -d display_startup_errors=on --ri blackfire command.
  • The output of blackfire-agent -v command.
  • The content of the Probe log file.
  • The content of the Agent log file.

Here's how to get the logs:

  1. Increase logging for the agent

    Increase the Agent log level to debug by configuring it with log-level=4 (refer to the Agent configuration for more information). Default log files are /var/log/blackfire/agent.log on Linux and /usr/local/var/log/blackfire/agent.log on OSX. On Windows, copy/paste the console output. Do not forget to restart the Agent to reload its configuration.

  2. Increase logging for the probe

    Increase the Probe log level to debug by configuring it with blackfire.log_level=4 and blackfire.log_file=/tmp/blackfire.log (refer to the Probe configuration for more information). Do not forget to restart the webserver or PHP-FPM to reload the configuration.

Support