Troubleshooting common deployment issues
This section provides the list of solutions and workarounds for common problems with deployments in PhpStorm.
Collecting PhpStorm 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.
Collect deployment logs
Select in the main menu.
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.webDeploymentIssues with issues with SSH/SFTP:
#com.intellij.ssh
Click OK and reproduce the issue.
Locate the log file by selecting (for Windows and Linux) or (for macOS).
If necessary, you can locate the log manually:
- Syntax
%HOMEPATH%\.<product><version>\system\log
- Example
C:\Users\JohnS\.PhpStorm2021.2\system\log
- Syntax
~/Library/Logs/<product><version>
- Example
~/Library/Logs/PhpStorm2021.2
- Syntax
~/.<product><version>/system/log
- Example
~/.PhpStorm2021.2/system/log
The most recent log file is named idea.log; older files names end with a number, that is idea.log.1, idea.log.2, and so on. In most cases you need only the most recent one.
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 (for example, 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 Deployment: Connection Tab for the server.
Limit the 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 Deployment: Connection Tab for the server.
File transfer becomes unresponsive
This can happen in case PhpStorm tries to resolve an IPv4 host via IPv6. By default, PhpStorm only listens for incoming IPv4 connections. To make sure IPv6 is disabled, check the PhpStorm JVM options:
Select from the main menu.
In the .vmoptions file that opens, make sure the
-Djava.net.preferIPv4Stack=trueline is present.Restart PhpStorm.
Otherwise, to enable IPv6 support, delete the -Djava.net.preferIPv4Stack=true line. In this case, make sure to add the IPv6 entry for your host to the /etc/hosts file.
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 Map project folders to 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 Deployment page of the Settings/Preferences dialog Ctrl+Alt+S. Open the Excluded Paths tab for the server and remove the excluded path. 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.
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 default new project settings are used to configure the default settings for new projects and do not affect the currently opened projects. To configure settings for the current project, 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?
When uploading folders and configuring mappings, note the following:
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 popup menu with the list of servers. Refer to Configure 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:
Select and start recording a Macro.
Select <server name> and close the sync window.
Stop recording the Macro by selecting from the main menu.
Set the Macro name, for example Sync with <server name>.
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:
Make use of the integrated database tools and run the required DDL and SQL statements manually.
Work with Phing and set up a DBDeploy task.
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, upload the processed files instead.
Note that the Skip external changes checkbox must be cleared on the Options page for this to work.
Sometimes files are not uploaded automatically
By default, PhpStorm uploads the files if they are changed by some external processes (VCS, transpilers, and so on). If the files are not uploaded, make sure that the Upload changed files automatically to the default server on the Options page is set to Always and the Skip external changes checkbox is cleared.
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 Deployment: Connection Tab for the selected server.
Limiting the number of concurrent FTP connections may also help in this situation. To do this, open the Deployment: Connection Tab 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 automatically to the default server to Always and clear the Skip 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.
FTPS troubleshooting
PhpStorm cannot establish connection with an FTPS server
If an FTPS server is configured to use TLS 1.0 / TLS 1.1, PhpStorm cannot connect to it and the following error message is displayed:
This happens because PhpStorm supports connecting to servers via TLS 1.2 and later. Using TLS 1.0 and TLS 1.1 is not supported, since these protocols are deprecated and considered insecure.
As a workaround, you can enable TLS 1.0 / TLS 1.1 support by adjusting the PhpStorm JVM options. Note that using outdated protocols can and will introduce security risks to your environment and consider it to be a last resort option.
Create a file custom.java.security with the following contents:
jdk.tls.disabledAlgorithms=SSLv3, RC4, DES, MD5withRSA, \ DH keySize < 1024, EC keySize < 224, 3DES_EDE_CBC, anon, NULL, \ include jdk.disabled.namedCurvesSelect from the main menu.
In the .vmoptions file that opens, add the following line:
-Djava.security.properties=${PATH_TO_CREATED_FILE}/custom.java.securityReplace
{PATH_TO_CREATED_FILE}with the path to the created custom.java.security file.Restart PhpStorm.
Known issues
Is rsync supported to synchronize files and folders with a deployment server?
No. If you feel this should be part of PhpStorm vote for this issue.