# Como corrigir o erro de File Upload por permissões de pasta no ACF PRO

O erro de File Upload por permissões de pasta no ACF PRO acontece quando o campo File usa a media popup nativa do WordPress para enviar um arquivo, mas a pasta wp-content/uploads não tem permissão de escrita para o usuário do servidor web, e o upload falha antes de o arquivo ser anexado ao campo.

## O que é erro de File Upload por permissões de pasta no ACF PRO?

O erro de File Upload por permissões de pasta no ACF PRO surge no campo File, um tipo de campo que, segundo a documentação oficial do ACF, permite enviar e selecionar um arquivo usando a janela de mídia nativa do WordPress (a native WP media popup). Quando você clica em adicionar arquivo e arrasta um documento para enviar, quem grava o arquivo não e o ACF: e o próprio WordPress, que escreve o arquivo dentro de wp-content/uploads. O ACF apenas guarda a referencia (o ID, a URL ou o array do anexo, conforme o Return Format configurado).

A falha aparece quando a pasta de uploads não tem permissão de escrita para o usuário que roda o PHP no servidor. O WordPress não consegue mover o arquivo do diretório temporario para a pasta de destino, devolve um erro de upload, e o campo File do ACF fica vazio porque nenhum anexo foi criado. Por isso o sintoma parece ser do ACF, mas a causa raiz esta nas permissões do diretório wp-content/uploads e na propriedade (ownership) dos arquivos, não no plugin.

## Como identificar

- Ao enviar um arquivo pela janela de mídia do campo File aparece a mensagem 'Não foi possível gravar o arquivo no disco.' ou, em ingles, 'Unable to create directory wp-content/uploads. Is its parent directory writable by the server?'.
- O upload trava na barra de progresso, o arquivo nunca termina de subir e o campo File do ACF continua vazio depois de fechar a janela.
- Outros campos File do ACF que já tinham arquivos antigos continuam funcionando, mas qualquer envio novo falha.
- A mensagem 'Falha ao processar o erro do servidor' (HTTP error) aparece na media library ao tentar arrastar o arquivo para enviar.
- No log de erros do PHP surge um aviso de move_uploaded_file ou de permissão negada (Permission denied) apontando para o caminho wp-content/uploads.

**Antes de começar:** Antes de alterar permissões ou propriedade de pastas e de mexer em limites do PHP em producao, faca um backup completo do site (arquivos e banco de dados) ou teste em um ambiente de staging. Nunca aplique 777 na pasta uploads: isso libera escrita para qualquer processo e e um risco de segurança; 755 nas pastas e 644 nos arquivos são os valores indicados.

## Como prevenir

- Mantenha as pastas em 755 e os arquivos em 644 dentro de wp-content/uploads, com o dono igual ao usuário do servidor web, conforme a orientacao de permissões do WordPress.
- Evite copiar arquivos para o servidor como root ou por um usuário diferente do PHP, para não herdar uma propriedade que bloqueia o upload do ACF depois.
- Defina upload_max_filesize e post_max_size do PHP com folga acima do maior arquivo esperado e alinhe o Maximum file size do campo File a esse limite.
- Documente no campo File quais extensões são aceitas na opção Allowed File Types, para evitar recusas silenciosas de upload por tipo de arquivo.

Erros relacionados

- [Como corrigir Custom Fields que não aparecem no frontend no ACF PRO](https://full.services/wp-fixer/corrigir-custom-fields-frontend-acf-pro/)
- [Como corrigir o Gallery Field com imagens que não carregam no ACF PRO](https://full.services/wp-fixer/corrigir-gallery-field-imagens-acf-pro/)
- [Como corrigir o Repeater Field que não salva dados no ACF PRO](https://full.services/wp-fixer/corrigir-repeater-nao-salva-acf-pro/)

## Causa

- A pasta wp-content/uploads (ou a subpasta do ano e mes corrente, como uploads/2026/06) esta com permissão restritiva, sem o bit de escrita para o usuário que roda o PHP, e o WordPress não consegue mover o arquivo enviado pelo campo File para o destino.
- O dono (ownership) da pasta uploads e diferente do usuário do servidor web (por exemplo, arquivos copiados via root pertencem a root e não ao usuário do PHP-FPM), entao mesmo com 755 a escrita e negada para quem processa o upload do ACF.
- O arquivo enviado excede o limite definido em upload_max_filesize ou post_max_size do PHP, ou estoura o Maximum file size configurado no próprio campo File do ACF, e o envio e abortado antes de gravar.
- A extensão do arquivo não esta na lista Allowed File Types do campo File do ACF, que adiciona validação de upload por tipo de arquivo, e o ACF recusa o envio mesmo com a pasta gravavel.
- Um plugin de segurança ou uma regra no servidor bloqueia a escrita ou a execução dentro de wp-content/uploads, fazendo o WordPress falhar ao criar a subpasta de destino do anexo.

## Como resolver

1. Confirme que o erro e de permissão de pasta: Tente enviar uma imagem direto pela Biblioteca de Mídia do WordPress, sem passar pelo ACF. Se o upload também falhar ali, o problema e do WordPress e da pasta uploads, não do campo File do ACF. Isso isola a causa antes de mexer em permissões.

```
Painel WP -> Mídia -> Adicionar nova mídia
Arraste um arquivo e observe se a falha de upload se repete fora do ACF
```

2. Ajuste a permissão da pasta uploads via FTP: Conecte ao site por um cliente FTP/SFTP, abra wp-content e ajuste a pasta uploads e suas subpastas para 755, que e o valor que a documentação do WordPress indica quando a pasta precisa ser gravavel. Aplique a permissão de forma recursiva nas subpastas de ano e mes.

```
Conecte por FTP/SFTP e navegue até wp-content
Clique com o botão direito em uploads -> Permissões de arquivo (File permissions)
Defina o valor numerico 755 e marque 'Aplicar recursivamente aos subdiretorios'
```

3. Corrija o dono (ownership) da pasta uploads via SSH: Se mesmo com 755 o upload do campo File continua falhando, o dono da pasta provavelmente não e o usuário do servidor web. Acesse por SSH e devolva a propriedade ao usuário do PHP (frequentemente www-data no Apache/Nginx). Confirme o usuário correto com seu provedor de hospedagem antes.

```
chown -R www-data:www-data wp-content/uploads
find wp-content/uploads -type d -exec chmod 755 {} ;
find wp-content/uploads -type f -exec chmod 644 {} ;
```

4. Verifique os limites de tamanho do PHP e do campo: Se a pasta já esta gravavel mas arquivos grandes ainda falham, o upload pode estar batendo no limite do PHP ou no Maximum file size do próprio campo File. Aumente os limites do PHP e revise a configuração do campo no ACF.

```
Painel WP -> Ferramentas -> Saude do site -> Informações -> Servidor (veja upload_max_filesize e post_max_size)
Painel WP -> ACF -> abra o Grupo de Campos -> campo File -> revise 'Maximum file size'
Ajuste upload_max_filesize e post_max_size no php.ini ou no .htaccess para um valor maior que o arquivo enviado
```

5. Confira a lista Allowed File Types do campo: Se o erro so acontece com certas extensões, o campo File pode estar recusando o tipo de arquivo. A documentação do ACF indica que o campo adiciona validação de upload por tipo: deixe a lista em branco para aceitar todos ou inclua a extensão desejada separada por virgula.

```
Painel WP -> ACF -> Grupos de Campos -> abra o grupo e o campo File
Em 'Allowed File Types', deixe vazio para todos ou liste as extensões (ex.: pdf, jpg, png)
```


## Código

```bash
# Ajuste de permissoes e dono da pasta de uploads (rode via SSH na raiz do WordPress)
# Confirme o usuario do servidor web com seu provedor (ex.: www-data, nginx, apache).

# 1. Devolve a propriedade da pasta uploads ao usuario do PHP/servidor web
chown -R www-data:www-data wp-content/uploads

# 2. Pastas em 755 (a documentacao do WordPress indica esse valor quando a pasta precisa ser gravavel)
find wp-content/uploads -type d -exec chmod 755 {} ;

# 3. Arquivos em 644
find wp-content/uploads -type f -exec chmod 644 {} ;

# 4. Confirma se o usuario do PHP consegue escrever (deve retornar 'ok')
sudo -u www-data test -w wp-content/uploads && echo ok || echo "sem permissao de escrita"
```

## Perguntas frequentes

### Por que o campo File do ACF PRO não consegue enviar arquivos

Na maioria dos casos a pasta wp-content/uploads não tem permissão de escrita para o usuário do servidor web. O campo File usa a janela de mídia nativa do WordPress, que grava o arquivo em uploads; se a pasta não for gravavel, o upload falha e o campo fica vazio.

### Qual permissão a pasta uploads precisa ter para o ACF funcionar

A documentação do WordPress indica 755 para a pasta uploads quando ela precisa ser gravavel, e 644 para os arquivos. Também e preciso que o dono da pasta seja o mesmo usuário que executa o PHP, senao a escrita continua sendo negada.

### O erro de upload e do ACF ou do WordPress

A causa raiz costuma ser do WordPress. O campo File apenas abre a media popup nativa e guarda a referencia do anexo; quem grava o arquivo em disco e o WordPress. Se o upload falha também direto na Biblioteca de Mídia, o problema esta na pasta uploads.

### Devo usar 777 na pasta uploads para resolver

Não. O 777 libera escrita para qualquer processo do servidor e e um risco de segurança. Use 755 nas pastas e 644 nos arquivos e corrija o dono (ownership) para o usuário do servidor web, que resolve o problema sem expor o site.

### O tamanho do arquivo pode causar a falha de upload no ACF

Pode. Se o arquivo passa do upload_max_filesize ou post_max_size do PHP, ou do Maximum file size configurado no próprio campo File, o envio e abortado. Aumente os limites do PHP e revise a configuração de tamanho do campo no ACF.

### Por que so alguns tipos de arquivo falham no campo File

O campo File do ACF adiciona validação por tipo na opção Allowed File Types. Se a extensão não estiver na lista, o envio e recusado. Deixe a opção em branco para aceitar todos os tipos ou inclua as extensões desejadas separadas por virgula.

### Como descubro qual usuário do servidor precisa ser dono da pasta

Depende da configuração do servidor; em muitos casos e o www-data no Apache ou Nginx com PHP-FPM. Confirme com seu provedor de hospedagem e aplique o chown na pasta uploads para esse usuário antes de ajustar as permissões.

**Fonte:** [Advanced Custom Fields — File field](https://www.advancedcustomfields.com/resources/file/)