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.

Este post está licenciado sob CC BY-NC.