Common tools 

Force a redeploy 

There are times where you might want to trigger a redeployment of your application, such as to update environment access for a new developer or add custom TLS certificates. A redeploy reuses your built app and services.

To trigger a redeploy, follow these steps:

  1. In the management console, navigate to the environment you want to redeploy.
  2. Click Redeploy.

Run the following command:

platform redeploy

The redeploy takes place after any scheduled activities (either Running or Pending).

Clear the build cache 

You may find that you need to clear the build cache, such as when it’s grown too big or, in rare circumstances, when it’s corrupted. It may get corrupted when code is downloaded from a third-party language service like Packagist or npm while that service is experiencing issues.

To clear the build cache, run the following command:

platform project:clear-build-cache -p <PROJECT_ID>

The next build for each environment is likely to take longer as the cache rebuilds.

HTTP responses 502 Bad Gateway or 503 Service Unavailable 

If you see these errors when accessing your application, it indicates your application is crashing or unavailable.

Typical causes and potential solutions include:

  • Your .platform.app.yaml configuration has an error and a process isn’t starting or requests can’t be forwarded to it correctly.
    • Check your web.commands.start entry or your passthru configuration.
  • The amount of traffic coming to your site exceeds the processing power of your application.
  • Certain code paths in your application are too slow and timing out.
    • Check your code is running smoothly.
    • Consider adding an observability solution to get a better view of your application.
  • A PHP process is crashing because of a segmentation fault.
  • A PHP process is killed by the kernel out-of-memory killer.

Large JSON file upload failing 

When trying to upload a large JSON file to your API, you might see a 400 response code (Malformed request).

Platform.sh enforces a 10 MB limit on files with the application/json Content-Type header. To send large files, use the multipart/form-data header instead:

$ curl -XPOST 'https://example.com/graphql' --header 'Content-Type: multipart/form-data' -F file=large_file.json

Permission error creating a database 

If you try to use a user to create a database, you get an error saying permission denied to create database. The database is created for you and can be found in the path key of the $PLATFORM_RELATIONSHIPS environment variable.

Can’t write to file system 

If you attempt to write to disk outside a build hook, you may encounter a read-only file system error. Except where you define it, the file system is all read-only, with code changes necessary through git. This gives you benefits like repeatable deployments, consistent backups, and traceability.

You can write to disk a build hook to generate anything you need later. Or you can declare writable mounts, which are writable even during and after deploy. They can be used for your data: file uploads, logs, and temporary files.

Stuck build or deployment 

If you see a build or deployment running longer than expected, it may be one of the following cases:

  • The build is blocked by a process in your build hook.
  • The deployment is blocked by a long running process in your deploy hook.
  • The deployment is blocked by a long running cron job in the environment.
  • The deployment is blocked by a long running cron job in the parent environment.

To determine if your environment is being stuck in the build or the deployment, look at the activities log available in the management console or by running platform act.

If the activity has the result success, the build has completed successfully and the system is trying to deploy. If the result is still running, the build is stuck.

In most regions, stuck builds terminate after one hour. In older regions (us and eu), create a support ticket to have the build killed.

When a deployment is blocked, you should try the following:

  1. Connect to your environment using SSH.
  2. Find any long-running cron jobs or deploy hooks on the environment by running ps afx.
  3. Kill any long running processes with kill <PID>. Replace <PID> with the process ID shown by ps afx.

If a sync of activate process is stuck, try the above on the parent environment.

Slow or failing build or deployment 

Builds can take long time or fail. Most of the time, it’s related to an application issue. Here are a few tips that can help you find the exact cause.

Check for errors in the logs 

Invisible errors during the build and deploy phase can cause increased wait times, failed builds, and other problems. Investigate each log and fix any errors you find.

Build and deploy hooks 

build and deploy hooks can cause long build times. If they run into issues, they can cause the build to fail or hang indefinitely.

build hooks can be tested in your local environment. deploy hooks can be tested either locally or by logging into the application over SSH and running them there. Be careful not to test the scripts on production environments.

You can also test your hooks with these Linux commands to help debug issues:

time $cmd # Print execution time
strace -T $cmd # Print a system call report

Cron jobs 

Containers can’t be shutdown while long-running cron jobs and scheduled tasks are active. That means long-running cron jobs block a container from being shut down to make way for a new deploy.

Make sure your custom cron jobs run quickly and properly. Cron jobs may invoke other services in unexpected ways, which can increase execution time.