PhpStorm 2018.2 Help

Troubleshooting common deployment issues

This section provides the list of solutions and workarounds for common problems with deployments in PhpStorm.

Collecting deployment logs

If your issue is not addressed in this section, contact our support engineers. If asked to provide deployment logs, follow the instructions to collect them.

To collect deployment logs

  1. Select Help | Configure Debug Log in the main menu.

  2. In the Custom Debug Log Configuration dialog that opens, add the following lines depending on the issues you are experiencing:
    • Issues with deployment/synchronization: #com.jetbrains.plugins.webDeployment

    • Issues with issues with SSH/SFTP: #com.intellij.ssh

    ps collect deployment logs
  3. Click OK and reproduce the issue.

  4. Locate the log file by selecting Help | Show Log in Explorer (for Windows and Linux) or Help | Show Log in Finder (for macOS).

    If necessary, you can locate the log manually:


    The most recent log file is named idea.log; older files names end with a number, i.e. idea.log.1, idea.log.2, and so on. In most cases you need only the most recent one.

  5. Attach the log file(s) to the issue or forum thread.

General troubleshooting

Deployment is slow or fails

Deployment can be a resource-intensive operation, especially if a project or a deployment server contains lots of directories and files. In the Settings/Preferences dialog (Ctrl+Alt+S), navigate to Build, Execution, Deployment and explore the following configuration options, which can speed up deployment:

  • Exclude directories that are not needed from deployment (e.g. images). This can be done from the Deployment: Excluded Paths Tab page.

  • On the Options page, clear the Overwrite up-to-date files to skip uploading files that don't need to be uploaded.

  • Depending on the server, switching between active and passive transfer mode in the advanced FTP settings may help. This can be done by toggling Passive mode in the Advanced Options Dialog for the server.

  • Limit number of concurrent FTP connections. This can be done by toggling Limit concurrent connections and setting the number of connections (usually 3-5 concurrent connections is OK for any server if you experience problems with a greater number of connections) in the Advanced Options Dialog for the server.

Download/upload actions are not available

Download/upload actions may not be available because of a missing mapping. If a file or folder that you want to download is not configured in any mapping, PhpStorm will not download it. Mappings can be configured as described in the Mapping project folders with folders on the server and the URL addresses to access them.

For some actions, a default deployment server needs to be selected on the Deployment page of the Settings/Preferences dialog.

Some folders are not deployed

A common cause for folders not being deployed is when they are explicitly excluded. To solve this, in the Remote Host Tool Window right-click the given folder and select Remove Path From Excluded from the context menu. Once this is done, the folder will be deployed.

This can also be configured from the the Deployment page of the Settings/Preferences dialog. Open the Excluded Paths tab for the server and remove the excluded path. Please note that both the source and the target folders should be checked. Folders can also be excluded by name on the Options page under Exclude items by name.

The File | Synchronize command does not synchronize files with the deployment server

The File | Synchronize ( Ctrl+Alt+Y ) is not related to deployments: it synchronizes the files with the file system in case the external changes were not detected automatically by the IDE. To learn more about synchronizing files between the project and the deployment server refer to Uploading and Downloading Files.

Sharing deployment configurations between projects

Deployment Servers are configured at the IDE level: they are available for all projects and can be shared between them.

Note that only the name and connection details (specified on the Deployment: Connection Tab tab) are shared between projects: mappings and excluded paths are project-specific and have to be configured separately. Using this approach, connection details have to be entered just once, while mappings and excluded paths can be configured per-project, sharing the connection details. This can be useful when projects share the same deployment server and use the same connection settings. If connection settings are different between projects, they have to be configured for every project separately.

If necessary, you can set a server to be visible in a single project by selecting the Visible only for this project checkbox on the Deployment: Connection Tab

IDE settings do not allow me to configure mappings

The IDE settings are used to configure the default settings for future projects and do not affect the currently opened projects. To configure those, use the Settings/Preferences dialog (Ctrl+Alt+S.

Can subfolders within the same folder have different deployment settings? Can a local folder be deployed to multiple locations?

There are a couple of things to note about uploading folders and configuring mappings:

  • You can specify mappings for specific folders to different paths on the deployment server. This can be configured on the Deployment: Mappings Tab for the server.

  • You can exclude specific folders and files from being uploaded/downloaded. This can be configured on the Deployment: Excluded Paths Tab for the server.

  • You cannot upload the same folder (or subfolders) to different sites at once. A separate deployment configuration needs to be created for each of them and uploaded to each site one by one.

If this is what you want to do, we recommend automating the process with a capable tool. For example, Phing has an FTP task which can be used from PhpStorm. Within PhpStorm, you can use the Sync with Deployed... command and select from available deployment servers for every upload.

I cannot assign a keyboard shortcut to the Sync With Deployed to My Server menu item

It is not possible to assign a keyboard shortcut directly to the Sync With Deployed to <server name> command, only to the generic Sync with Deployed to... command, which will then display a pop-up menu with the list of servers. Refer to Configuring Keyboard Shortcuts for details.

If you do wish to assign a keyboard shortcut to a specific deployment server, it is possible to record a Macro and assign a shortcut to it instead:

  1. Select Edit | Macros | Start Macro Recording and start recording a Macro.

  2. Select Tools | Deployment | Sync With Deployed to <server name> and close the sync window.

  3. Stop recording the Macro by selecting Edit | Macros | Stop Macro Recording from the main menu.

  4. Set the Macro name, for example Sync with <server name>.

  5. Open in the Settings/Preferences dialog (Ctrl+Alt+S), select Keymap and find the Macros node. From the context menu of the new sync Macro that was just recorded, select Add keyboard shortcut and provide the desired shortcut.

How do I deploy a database using PhpStorm?

There are a couple of ways to deploy a database using PhpStorm:

Can I run a script or executable on my files before the upload occurs?

Things like minifying CSS, optimizing images, encoding PHP files using IonCube and so on are actions that you may want to execute before an upload happens. The best approach to do this is run them not when the upload is started, but when the files are changed, by using File Watchers in PhpStorm. When the time comes to upload them to a deployment server, simply upload the processed files instead.

Note that the Upload external changes checkbox must be selected on the Options page for this to work.

Sometimes files are not uploaded automatically

By default, only files the updated in the editor will be uploaded automatically. To enable automatic upload for files changed by external processes (VCS, transpilers, etc.), select the Upload external changes checkbox on the Options page.

Can I run pre- and post-deployment actions?

It's possible using Run/Debug configurations. You can create a fake Run/Debug Configuration or a Run/Debug configuration that should be the last step, and add the required steps under Before launch.

As an alternative, we recommend using Phing or any other build system to execute complex sequences of steps.

FTP troubleshooting

FTP issue: Invalid descendent file name "http:"

When a deployment server has been configured or when using the Test Connection button in the project settings, the Invalid descendent file name "http:" error is displayed. Note that all file names with a colon (:) in the name will be considered invalid.

This can happen if a file containing http: in its name exists in the project. The library that PhpStorm uses to connect to FTP (Apache Commons VFS) cannot read the contents of a folder containing such a file, which causes the operation to fail. The only solution is to remove the file containing http: in its name from the project.

PhpStorm seems to connect to the server but can't list files or perform upload

This may be because the deployment server requires a so-called passive FTP connection. To set this mode, select the Passive mode checkbox in the Advanced Options Dialog for the selected server.

Limiting the number of concurrent FTP connections may also help in this situation. To do this, open the Advanced Options Dialog for the selected server, select the Limit concurrent connections checkbox, and set the number of connections (usually, 3-5 concurrent connections is OK for any server if you experience problems with a higher number of connections).

Deploying files when changing branches using Git checkout

There are a couple of ways to go about deploying files when switching between branches using Git checkout:

  • One way is to configure deployments to always upload files and external changes. To do this, on the Options page, set Upload changed files to the default server to Always and select the Upload external changes checkbox. Note that this will upload all files to the server when switching branches.

  • Use git-ftp. It performs minimal uploads and is also able to mirror file and directory removals.

Known issues

Is rsync supported to synchronize files and folders with a deployment server?

No. If you feel this should be part of PhpStorm please vote for this issue.
Last modified: 10 October 2018