How I fixed WHMCS `StorageException` for `email_template_attachments` and `ticket_attachments`

I handled a production WHMCS incident that broke two critical operations: administrative email attachments and ticket attachments. The error was:

WHMCS\Exception\Storage\StorageException:
Cannot find storage setting for asset type "email_template_attachments"

Shortly after, the same failure pattern appeared for:

Cannot find storage setting for asset type "ticket_attachments"

Below is the exact troubleshooting sequence I executed.

1) Stack trace triage and scope isolation

The exception originated from:

WHMCS\File\Storage->createFilesystem()

This matters because the failure happens before actual file write/read operations. So this is not a plain filesystem permission issue at first touch; the storage driver cannot be instantiated for the requested asset type.

2) Why WHMCS fails here

WHMCS uses a storage abstraction layer backed by Flysystem. Asset types must be mapped to a valid storage backend (local/S3/FTP/etc.).

If a mapping is missing, WHMCS cannot build the filesystem instance and throws StorageException.

Missing mappings in this incident:

• email_template_attachments
• ticket_attachments

3) What I checked first (and ruled out)

3.1 configuration.php

No storage asset mapping lives there in modern WHMCS installs. Useful for DB/license/crypto/custom paths, but not for this exception.

3.2 assets.json

Not relevant for this failure mode in current WHMCS storage architecture.

4) Correct investigation path: database + internal storage config

Primary table:

tblstorageconfigurations

Secondary reference table:

tblconfiguration

Validation query:

SELECT *
FROM tblstorageconfigurations;

Result: missing valid bindings for both affected asset types.

5) Root cause in my case

A WHMCS upgrade had completed only partially for storage migration metadata. Core app was up, but those asset types had no effective storage configuration.

6) Fix implementation

6.1 Recreate storage mapping in Admin

Path in WHMCS:

System Settings -> Storage Settings

Actions:

1. Created a Local storage backend.
2. Set a persistent path outside web root.
3. Explicitly mapped:

• Email Template Attachments
• Ticket Attachments

Example path:

/home/user/whmcsdata/attachments

6.2 Enforce proper ownership and permissions

chown -R apache:apache /home/user/whmcsdata
chmod -R 755 /home/user/whmcsdata

(Adapt runtime user/group to your stack: apache, www-data, PHP-FPM pool user, etc.)

6.3 SELinux validation (enforcing hosts)

sestatus
ausearch -m avc -ts recent

If required:

setsebool -P httpd_unified 1
semanage fcontext -a -t httpd_sys_rw_content_t "/home/user/whmcsdata(/.*)?"
restorecon -Rv /home/user/whmcsdata

In this incident, SELinux was not the root cause, but the check is mandatory for a reliable RCA.

7) Final acceptance tests

After mapping + permissions + SELinux checks:

• tested admin mail flow with attachments
• tested ticket attachment upload/read
• executed cleanup workflow in admin

Admin -> System Cleanup

Result: exception gone, email and ticket attachment pipelines restored.

8) Operational checklist I now run after every WHMCS update

1. Review all entries in Storage Settings.
2. Validate mapping for critical asset types.
3. Keep storage paths outside public_html.
4. Verify runtime ownership and permissions.
5. Check SELinux AVC logs on enforcing hosts.
6. Run end-to-end functional tests (not only UI smoke checks).

9) Bottom line

For Cannot find storage setting for asset type, the effective fix is storage mapping integrity, not configuration.php tuning. Incomplete upgrade migrations can leave asset types unmapped.

The stable remediation path is:

• restore valid storage bindings
• enforce correct filesystem and MAC context
• validate with real workflows

That closes the incident with traceable, production-safe evidence.

This post is licensed under CC BY-NC.