Skip to main content
Version: 2026.2

FAQ & Troubleshooting

Infrastructure & Architecture​

Q: What exactly is the function of Nginx within the application (reverse proxy, load balancer, etc.)? Or does load balancing happen one level higher within the VPN of the Upsun region (keyword Availability Zones)?
Nginx is used as a web server and the reverse proxy for PHP/FPM, so the actual Pimcore application.
There is no loadbalancing in case of a Grid project, as there is only 1 instance running at the same time for each containers.

Q: What are the scaling options for the individual services ie MariaDB, within a Pimcore application? Which services can actually be scaled (e.g. multiple containers)? What exactly happens there?
Currently on Pimcore PaaS there is no option to have multiple instance of the same app container - horizontal scaling.
We can only provide more resources via T-shirt sizing or with flexible resources - vertical scaling.
Take note that you need to respect your plan sizing and properly size all resources.

However, the underlying infrastructure is able to provide both vertical or horizontal scaling, this is exposed in Upsun, but not yet in Pimcore PaaS. We are also working on autoscaling support. It should arrive soon on Pimcore PaaS but we don't have an exact ETA. You can learn more about how autoscaling works on the underlying infrastructure here: https://devcenter.upsun.com/posts/autoscaling-deep-dive/

Q: What are the PHP workers underneath the services for or what is their function?
Worker instances are well explained here https://fixed.docs.upsun.com/create-apps/workers.html#workers-vs-cron-jobs In our use case, workers are handling message transports - message:consume commands.

Q: Is Mercure always installed/activated in a Pimcore PaaS application or only when Pimcore Direct Edit is used?
Mercure is available as a stand-alone app within the applications.yaml and can be used as needed. By default it's commented out.

Configuration & Setup​

Q: How do I configure a custom domain?
Custom domains are configured in your .platform/routes.yaml file and then added via the Pimcore PaaS Console. Follow the domain setup guide for full instructions on DNS configuration and TLS certificates.

Q: Does the deploy hook run on every push, including branch pushes?
The deploy hook runs whenever a new commit is pushed to any branch (including non-production branches), as each new commit triggers a new build and deployment. However, a redeploy without code changes only triggers the post_deploy hook — the build and deploy hooks are skipped. Ensure that commands in your deploy hook (such as database migrations) can handle being run on each new deployment safely. See the hooks comparison for details.

Q: What prerequisites and training should my team have before starting with Pimcore PaaS?
Initial setup should be performed by developers with Pimcore, Git and CI/CD experience. If your team is new to Pimcore, complete the Pimcore Academy and consult the Upsun (Platform.sh) documentation and Pimcore docs before starting. This prevents configuration errors and accelerates implementation.

Q: Why do runtime writes to the filesystem fail after deployment?
After the build phase, the container filesystem is read-only. Attempting to write to non-mounted paths will fail — code changes can only be deployed via Git push. Any runtime writes must target the designated mount points configured in applications.yaml. Review the Working with definition files section to understand which directories are writable at runtime.

The PaaS install profile addresses this by implementing InstallStepFilterInterface to skip steps that would write to the read-only filesystem (e.g., WriteEnv, WriteDoctrineConfig, RegisterBundles). See the Install Profile documentation for details.

Resource Sizing & Performance​

Q: How much memory should I allocate for my database?
Allocating insufficient RAM for your database leads to performance degradation — increased I/O latency and slower queries which can degrade entire system performance. Allocate RAM that at least matches your database size +10% to avoid performance issues. Monitor your database size and adjust resources accordingly. Use the Pimcore PaaS Console to check current resource usage and plan capacity.

Q: How do I choose the right plan tier for my asset workload?
Underestimating asset sizing when selecting your plan tier can dramatically impact performance. Asset manipulation is a resource-heavy operation, and an inadequate plan can cause system-wide slowdowns. To avoid this:

Email / Mail Delivery​

Q: How does outgoing email work on Pimcore PaaS?
Pimcore sends mail through Symfony Mailer, using the transport defined under framework.mailer (in config/config.yaml). With Pimcore's default native://default transport, the outbound path on PaaS is:

Pimcore (\Pimcore\Mail) → Symfony Mailer transport → /usr/sbin/sendmail (msmtp) → platform SMTP relay (PLATFORM_SMTP_HOST)

There is no local MTA in the container. /usr/sbin/sendmail is a symlink to msmtp, which relays to the platform's SMTP service exposed via the PLATFORM_SMTP_HOST environment variable. Outgoing mail also has to be enabled on the environment (enable_smtp, on by default for production and configurable per environment).

Q: Test emails work from a plain PHP script (mail()), but Pimcore shows "could not send email". Why?
This is the most common mail issue on PaaS and it comes from a transport misconfiguration, not from the platform or PHP.

The two paths use different sendmail invocations:

PathCommand invokedmsmtp result
PHP mail()/usr/sbin/sendmail -t -i (from php.ini sendmail_path)✅ supported
Symfony native://default (Pimcore default)uses php.ini sendmail_path → /usr/sbin/sendmail -t -i✅ supported
Symfony sendmail://default/usr/sbin/sendmail -bs❌ rejected

msmtp does not support the -bs (interactive SMTP) mode. When the transport is sendmail://default, Symfony invokes /usr/sbin/sendmail -bs, msmtp exits immediately with sendmail: unsupported operation mode bs, and Symfony raises:

Symfony\Component\Mailer\Exception\TransportException:
Connection to "process /usr/sbin/sendmail -bs" has been closed unexpectedly.

Pimcore wraps this into the generic "could not send email" in the admin UI. Because PHP mail() uses -t -i (which msmtp does support), a plain PHP test succeeds while Pimcore fails — a very misleading symptom.

Fix: in config/config.yaml, do not force sendmail://default. Use one of:

# Option 1 — recommended: let Pimcore use the default `native://default`
#            (reads php.ini sendmail_path = "/usr/sbin/sendmail -t -i", msmtp-compatible).
#            Simply do not override framework.mailer.transports.main.

# Option 2 — explicit sendmail command msmtp accepts:
framework:
    mailer:
        transports:
            main: 'sendmail://default?command=/usr/sbin/sendmail -t -i'

# Option 3 — talk to the platform SMTP relay directly:
framework:
    mailer:
        transports:
            main: 'smtp://%env(PLATFORM_SMTP_HOST)%:25'

⚠️ A sendmail://default value is often left over from a local development config (where a local sendmail/mailpit does support -bs). Make sure such an override is not carried into your PaaS branches, and remember it will break any environment it is deployed to — including production if merged.

Q: How do I diagnose a mail problem myself?
Work top-down. SSH into the affected environment with pimcore-cloud ssh (add -e <environment> to target a specific branch) and run:

  1. Check the active mailer transport — this alone reveals the -bs problem:

    php bin/console debug:config framework mailer

    Look at transports.main. native://default is fine; sendmail://default is the trap described above.

  2. Send a real test through the Symfony transport (this is what Pimcore uses):

    php bin/console mailer:test recipient@example.com \
      --from="noreply@your-domain.com" \
      --subject="PaaS mailer test"
    • Exit code 0 and no output → the transport delivered to the relay.
    • A TransportException (e.g. the -bs error above) → transport misconfiguration; fix per the question above.
    • Note: mailer:test exercises the transport layer only; it does not go through \Pimcore\Mail, so it ignores the Pimcore sender config and the debug redirect (see below).

  3. Verify the Pimcore sender is set — a real Pimcore action (e.g. Settings → Users → send invitation link) needs a valid From:

    php bin/console debug:config pimcore email

    Confirm sender.email / sender.name are populated. If system_settings uses settings-store, check the runtime value in Pimcore's System Settings instead; debug:config only shows the container configuration. An empty sender can make Pimcore mail fail even when the transport is healthy.

  4. Confirm outgoing mail is enabled and the relay is reachable:

    echo "PLATFORM_SMTP_HOST=[$PLATFORM_SMTP_HOST]"   # empty ⇒ outgoing email disabled for this environment

    enable_smtp is off by default on some non-production environments; enable it in the Pimcore PaaS Console if outgoing email is required there.

  5. Isolate the OS layer (only if the transport check is inconclusive) — test msmtp directly to see the SMTP dialogue:

    printf 'From: noreply@your-domain.com\nTo: you@example.com\nSubject: msmtp test\n\nbody\n' | msmtp -v -t

    A successful run shows MAIL FROM and RCPT TO answered with 250, DATA answered with 354, and final message acceptance answered with 250. If this works but mailer:test fails, the problem is the Symfony transport config, not the platform.

Q: My test emails are accepted (exit 0) but never arrive. What now?
Exit 0 means the message was handed to the relay successfully; delivery is then subject to normal email rules:

  • Delivery lag — the platform relay can take a few minutes; wait before concluding it failed.
  • Spam filtering — check the spam folder, especially for messages with a generic From or an empty envelope sender.
  • Debug redirect — if pimcore.email.debug.email_addresses is set (visible in php bin/console debug:config pimcore email), Pimcore redirects all \Pimcore\Mail messages to those addresses instead of the real recipients. This is expected in debug/dev mode; mailer:test is not affected by it because it bypasses \Pimcore\Mail.
  • Deliverability / SPF-DKIM — for production domains, configure SPF/DKIM for your sender domain so external providers (Gmail, Outlook, …) accept the mail.

See Also​