Como resolvi o `storageexception` no WHMCS (`email_template_attachments` e `ticket_attachments`)

Recentemente enfrentei um incidente em produção no WHMCS com impacto direto em duas frentes operacionais: envio de e-mails administrativos com anexos e manuseio de anexos de tickets. O erro apresentado no stack trace foi:

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

Na sequência, o mesmo padrão ocorreu para:

Cannot find storage setting for asset type "ticket_attachments"

Este artigo documenta exatamente o que foi validado, o que descartei, a causa raiz encontrada e o procedimento aplicado para correção definitiva.

1) Leitura do stack trace e delimitação do escopo#

A exceção era gerada na cadeia de storage interno do WHMCS, com origem em:

WHMCS\File\Storage->createFilesystem()

Esse ponto é decisivo: a falha acontece antes de I/O de arquivo efetivo. Ou seja, o erro não começa em chmod, chown ou disco cheio. O sistema está falhando ao montar a configuração lógica do filesystem para o asset type requisitado.

2) Contexto técnico: por que esse erro ocorre#

WHMCS utiliza abstração de storage sobre Flysystem (League\Flysystem). Cada tipo de ativo (attachments, downloads, templates etc.) precisa estar vinculado a uma configuração válida de backend (local, S3, FTP, entre outros).

Quando o asset type solicitado não encontra mapeamento em storage, a factory não consegue instanciar o driver e o WHMCS lança StorageException.

No meu caso, os tipos sem mapeamento eram:

• email_template_attachments
• ticket_attachments

3) Hipóteses iniciais descartadas (com evidência)#

3.1 configuration.php#

Primeiro passo foi revisar configuration.php buscando chave de storage. Não existe configuração de asset mapping ali. Esse arquivo cobre banco, licença, criptografia e diretórios customizados, mas não resolve esse tipo de erro.

Conclusão: não era ponto de correção.

3.2 assets.json#

Também validei a hipótese de arquivo legado de assets. Em instalação WHMCS moderna padrão, esse arquivo não participa da configuração de storage para os tipos citados.

Conclusão: abordagem desatualizada para esse cenário.

4) Investigação correta: camada de banco e configuração interna#

Com o trace delimitado, fui direto para validação de metadados de storage em banco.

Tabela principal investigada:

tblstorageconfigurations

Tabela auxiliar de conferência:

tblconfiguration

Consulta inicial:

SELECT *
FROM tblstorageconfigurations;

Resultado: não havia vinculação válida para email_template_attachments e ticket_attachments.

5) Causa raiz no incidente#

O ambiente tinha passado por atualização de WHMCS e a migração de storage ficou incompleta para parte dos asset types. Na prática, o sistema estava íntegro para outros módulos, mas sem mapa de armazenamento para anexos de e-mail/ticket.

Isso explica o comportamento intermitente por funcionalidade: o problema não era global de filesystem, era específico de asset mapping ausente.

6) Correção aplicada (passo a passo)#

6.1 recriação do storage no painel#

No WHMCS Admin:

System Settings -> Storage Settings

Ações executadas:

1. Criei storage backend do tipo Local.
2. Defini caminho persistente fora do public_html.
3. Associei explicitamente os asset types:

• Email Template Attachments
• Ticket Attachments

Exemplo de path aplicado:

/home/user/whmcsdata/attachments

6.2 hardening de path de storage#

Critérios adotados:

• diretório fora da raiz web pública
• ownership coerente com usuário efetivo do PHP-FPM/Apache no host
• permissão mínima funcional para leitura/escrita do serviço

Aplicação no servidor:

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

Observação operacional: o usuário/grupo deve refletir seu runtime (apache, www-data, pool user etc.).

6.3 validação de SELinux (ambiente enforcing)#

Como o host roda SELinux ativo, validei camada MAC para eliminar bloqueio silencioso:

sestatus
ausearch -m avc -ts recent

Quando necessário, opções de correção:

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

No incidente específico, SELinux não foi causa raiz, mas essa validação é mandatória para fechar diagnóstico com segurança.

7) Teste de aceite pós-correção#

Após mapear storage + permissões + validação de contexto:

• executei rotinas administrativas que acionam anexos
• validei envio de e-mail com attachment
• validei upload/leitura de anexo em ticket
• rodei limpeza operacional no admin

Fluxo utilizado:

Admin -> System Cleanup

Resultado: exceção eliminada, fluxo de anexos normalizado para os dois asset types.

8) Checklist técnico que passei a usar após upgrades de WHMCS#

1. Validar System Settings -> Storage Settings imediatamente após update.
2. Conferir se todos os asset types críticos estão vinculados a storage ativo.
3. Auditar path de storage fora do public_html.
4. Revisar ownership/permissões do diretório.
5. Em hosts com SELinux, validar AVC logs antes de concluir RCA.
6. Executar teste funcional real (ticket + e-mail com anexo) e não apenas teste superficial de login/página.

9) Conclusão operacional#

Quando o WHMCS retorna:

Cannot find storage setting for asset type

o foco correto é configuração de storage e mapeamento de asset type, não configuration.php e não arquivo legado de assets.

No meu caso, a raiz foi migração incompleta pós-update. A correção definitiva veio de:

• recriar/vincular storage adequado
• garantir path e permissões corretas
• validar SELinux
• fechar com teste funcional de ponta a ponta

Esse procedimento reduz tempo de indisponibilidade e evita intervenção cega em filesystem sem evidência técnica.

Veja também

Desenvolvimento Troubleshooting BIND9 + WHMCS: sintaxe DNS, cron de alta performance e integração eNom

Banco de Dados Sobrevivendo à exaustão de conexões no MariaDB com CloudLinux sem downtime

Infraestrutura Desincronização de handshake do MySQL em ambientes multi-tenant: cPanel, CloudLinux e CageFS

Este post está licenciado sob CC BY-NC.