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 diagnose automatically. If this issue occurs, please follow these steps:

  1. Check versions

    Ensure you're using the latest Agent, Probe and Companion. This is quite easy as this page 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.

  3. Make sure you selected the proper Environment

    If you are using the Premium or Enterprise Edition, you may have created and configured shared Environments. As each Environment has its own set of server credentials, specifying which Environment you are targeting when profiling will grant you the access rights. That can be done either via the drop-down box in the Chrome extension, or via specifying the --env option in the CLI.

  4. Check logs

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

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

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

  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.

  1. Contact our support

    Collect logs and contact our support.

Profile rejected - Hosting configuration

Hosting configuration (aka. Hosters edition) is a special mode where you are allowed to profile any website hosted on your machine as soon as you are allowed to profile the agent environment. This allows end-users but also the Hoster to profile the websites in their own environments.

If you are not a hosted and get "A profile rejected", it usually means your blackfire credentials in PHP are not setup correctly but the ones in the agent configuration are.

To fix this, just remove the credentials (server_id and server_token) from the PHP configuration: most of the time they are not required.

If you actually want to profile using the credentials configured for PHP, then you need to select the environment accordingly.

If you still believe this is bug, please 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 server. If you encounter this issue, you can increase the timeout of the Agent by appending the following line to the Agent configuration:


I Can't Find a Solution on this Page

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, simply 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.