All page names need to be in English.
en da  de  fr  it  ja  km  nl  ru  zh

Flow Installation Hints

From TYPO3Wiki
Jump to: navigation, search
This page belongs to the Flow Team (category Flow)

Just leave your hints and comment on existing ones. For the Flow releases we will go through them and integrate them into the installation instructions / manual where it makes sense.

Database related

Collation issues

The default character set resp. collation should be, for MySql, utf8_unicode_ci. This should be applied to the database itself (the schema) in order to serve as sane defaults for new tables being set up with no explicit collation directions.

If something when wrong at a stage during the lifetime, you might end up with error messages like

Error Code: 1215. Cannot add foreign key constraint

This is a sign that the columns you intend to wire together have a different type, charset or collation. A different collation is even considered if one collation is inherited from the table, and one is defined explicitly!

In order to clean that up if you stumble upon these cases, follow the following steps:

Caution: We will set the character set to UTF-8, however, if your database is currently defined as something else, like latin-1, the content will be messed up because unlike the name suggests, the content itself it not converted.

  • Set/correct the database's character set and collation:
ALTER DATABASE `your_database` COLLATE 'utf8_unicode_ci';
  • Fetch the tables in this database which derive from the intended collation using the following SQL:
SELECT * FROM information_schema.tables WHERE TABLE_SCHEMA = 'your_database' AND TABLE_COLLATION != 'utf8_unicode_ci'
  • Examine the column TABLE_NAME in the result set, these are the tables where the collation does not match. In order to clean that up, you have to build a stack of SQL commands for each table name, you might do that in your favorite column-able editor or spreadsheet application:
ALTER TABLE `one_table` CONVERT TO CHARACTER SET utf8 COLLATE 'utf8_unicode_ci';

This will "recursively" (down to each column of that table) apply the appropriate definition.

Having done this, you should be able to create your foreign key constraints.

"Maximum function nesting level reached" fatal error

In case you get a fatal error message saying something like "Maximum function nesting level of '100' reached, aborting!", check your php.ini-file for settings regarding "xdebug" and modify/add a line xdebug.max_nesting_level = 500 (suggested value; the blog example requires at least a value of about 150).

Memory exhausted during unit tests

If unit tests do not fully complete, it may be neccessary to extend the memory limit. Modify your php.ini and set it to at least 256M memory_limit = 256M

Usernames with "." don't work with workspace handling in BE editing

There is currently an issue with usernames containing a dot in it while trying to edit a page in the "content" module of the backend. TYPO3 is adding a "@user-USERNAME.html" to the websites URI and if you have a "." in your username (like "") you'll get a 404 message displayed. See #27991

Suhosin related notes

Caution: Suhosin provides security to your PHP environment. Only make changes to the configuration if you know and are aware of what you are doing and what influences these changes have.

General hints when using Suhosin

When using Suhosin it's likely you sometimes experience some unexpected behavior when developing with TYPO3 Flow. If so, it's always a good idea also to check /var/log/syslog because in default "configuration" ( it's set to log Alerts. When suhosin prevents any action, it's logged there. Such an alert may look like:

ALERT - configured GET variable value length limit exceeded - dropped variable '__widgetContext'

An additional help may be setting the "filter action" ( to a value like 400 in order for you directly seeing that something went wrong.

Unit tests abort with a segfault

An additional abort may occur during unit tests in the combination of php with suhosin patch. A whitelist entry has to be added in this case. Check your suhosin.ini-file and modify/add a line suhosin.executor.include.whitelist = vfs://

Unexpected behavior with serialized objects in request arguments

Protected class's member names are prepended with an asterisk wrapped in null-bytes ( The suhosin-extension removes the complete variable if such a null-byte occurs. Check your suhosin.ini-file and modify/add the lines:

suhosin.get.disallow_nul = Off = Off

Some additional information: due to documentation that Off should work; at this author's case it didn't and setting to 0 (zero) was necessary. Also check if suhosin.request.disallow_nul must also be set.

Exceeding GET variable value length

In TYPO3 Flow, sometimes serialized objects are transferred via GET (e.g. Fluid widgets). This may exceed Suhosin's "default configuration" (, so you might want to set:

suhosin.get.max_value_length = 1024

Running on Windows OS's

PHP binary

If you haven't installed PHP to the default location (specified by the *PHP_BINDIR* constant which usually points to *C:/php*), you'll have to specify the path to your php binary explicitly:

Edit the file *…/Configuration/Settings.yaml* and set/uncomment the TYPO3.Flow.core.phpBinaryPathAndFilename directive. Please use single forward slashes, an uppercase drive letter in any case and avoid typical special characters like ~ or () (see for more information on this). The whole setting should read e.g.:

        phpBinaryPathAndFilename: 'C:/Programs/Zend/ZendServer/bin/php.exe'

If nothing works, it may be a good idea to add the executable to your PATH (if not there anyways) and just set this directive to php or php.exe.

Symbolic Links

TYPO3 Flow uses symbolic links to make public resources available to the browser without needing to copy them to an accessible directory. Unfortunately Windows usually requires a user with privileged rights for that, so you might get errors like the following when trying to create a symlink via PHP:

  Warning: symlink(): Cannot create symlink, error code(1314)

To get the creation of symbolic links work (only Windows Vista and above), open the local policy editor secpol.msc and locate Security Settings > Local Policies > User Rights Management > Create symbolic links and grant this permission to the appropriate group. I myself chose "Everybody", because there is no reason why a non-admin should not be allowed to create symbolic links IF he has write permission anyway. (the German description is Sicherheitseinstellungen > Lokale Richtlinien > Zuweisen von Benutzerrechten > Erstellen symbolischer Verknüpfungen).

  • Note:* Symlinks are created on the first run and if you install new packages with public resources. If you can't get the above working, you can also run the command prompt *as administrator* and execute the flow batch once:

If this is not an option for you, creation of symlinks can be replaced with copying by changing the strategy:

            mirrorMode: copy 

Command Line Tool

To run the flow command line interface, make sure the directory of your php binary is in the *path environment variable*. You can add it to the path by executing:

   SET path=C:/path/to/php;%path%;

An alternative solution is to edit the path in the *flow.bat* script in the root directory. Afterwards you can run the CLI:

   > CD path/to/your/flow/installation
   > flow.bat help
  • Note:* If you get an error because PHP could not create the required symlinks, follow the steps mentioned above


If you want to clone TYPO3 Flow to a Windows system, Git needs to be configured so it does not convert new line characters. This is done with the setting core.autocrlf and should be set to "input":

   git config --global core.autocrlf input

If you don't do this you might run into errors like "Uncaught Exception The ... annotation for ... seems to be invalid."