# Como corrigir o File Field do ACF PRO quando o upload não funciona

O upload do File Field do ACF PRO não funciona quando o tipo de arquivo está fora da lista permitida, o limite de tamanho rejeita o envio, a opção Library restringe a seleção, ou o Return Format escolhido não casa com o código do template, deixando o download quebrado.

## O que é File Field do ACF PRO quando o upload não funciona?

O File Field do ACF PRO é o campo que permite anexar um arquivo (PDF, ZIP, DOCX, planilha) a um post, página ou opção, reaproveitando a Biblioteca de Mídia do WordPress. Segundo a documentação oficial do ACF, ele guarda o resultado em um de três formatos definidos pela opção Return Format: File Array (array com url, filename, title, type, sizes), File URL (apenas a string da URL) ou File ID (o inteiro do attachment). O upload não funcionar pode significar duas falhas diferentes: o arquivo não chega a ser salvo no campo, ou ele salva mas o link de download aparece vazio ou quebrado no frontend.

A causa raiz mais comum não é um bug do plugin, e sim configuração. A opção Allowed file types restringe as extensões aceitas; o WordPress bloqueia tipos MIME não permitidos no núcleo; os limites Minimum e Maximum rejeitam arquivos fora da faixa de tamanho; e a opção Library com 'Uploaded to post' esconde arquivos já existentes na mídia. Quando o arquivo até salva mas o download quebra, o motivo quase sempre é o Return Format divergir do código do template, porque cada formato exige uma forma diferente de ler o valor com get_field.

## Como identificar

- Ao selecionar um arquivo na janela de mídia, aparece o aviso 'Sorry, this file type is not permitted for security reasons' e o upload é recusado.
- O arquivo some do campo depois de salvar o post: o File Field volta vazio mesmo após escolher o arquivo na Biblioteca de Mídia.
- O link de download no frontend aponta para um endereço vazio, para 'Array' literal, ou para um número, em vez da URL real do arquivo.
- Surge o erro 'O arquivo enviado excede a diretiva upload_max_filesize do php.ini' ou um aviso de tamanho máximo ao tentar enviar um arquivo grande.
- Com a opção Library marcada como 'Uploaded to post', arquivos que já estão na Biblioteca de Mídia não aparecem para seleção no campo.

**Antes de começar:** Antes de editar o functions.php ou liberar tipos MIME, faça um backup completo do site (arquivos e banco de dados) ou teste primeiro em staging. Libere apenas as extensões estritamente necessárias, porque permitir tipos MIME arbitrários amplia a superfície de ataque por upload de arquivos maliciosos.

## Como prevenir

- Padronize o Return Format de cada File Field no momento de criar o campo e documente qual formato o template espera, para o link de download nunca quebrar.
- Liste em Allowed file types apenas as extensões realmente esperadas, evitando tanto bloqueios surpresa quanto a aceitação de tipos perigosos.
- Confira upload_max_filesize e post_max_size do PHP na Saúde do site antes de pedir uploads grandes aos editores, deixando margem acima do maior arquivo previsto.
- Mantenha a opção Library coerente com o uso: 'All' quando os editores reaproveitam mídia, 'Uploaded to post' apenas quando o arquivo deve pertencer só àquele post.

Erros relacionados

- [Como corrigir o erro de File Upload por permissões de pasta no ACF PRO](https://full.services/wp-fixer/corrigir-file-upload-permissoes-acf-pro/)
- [Como corrigir o Image Field no ACF PRO](https://full.services/wp-fixer/corrigir-image-field-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/)

## Causa

- A opção Allowed file types do campo lista extensões específicas (ex.: 'pdf,zip') e o arquivo enviado tem extensão fora dessa lista, então o ACF recusa o upload antes de salvar.
- O tipo MIME do arquivo não está na allowlist do núcleo do WordPress (get_allowed_mime_types), então o WordPress bloqueia o envio com a mensagem 'this file type is not permitted', independentemente do ACF.
- Os limites Minimum ou Maximum do campo (em MB ou strings como '400 KB') rejeitam o arquivo por estar fora da faixa de tamanho configurada no grupo de campos.
- A opção Library do campo está em 'Uploaded to post', o que restringe a seleção apenas a arquivos enviados àquele post e esconde os demais itens da Biblioteca de Mídia.
- O Return Format do campo (File Array, File URL ou File ID) diverge da forma como o template lê o valor: o código usa $file['url'] num campo que retorna apenas a string da URL, ou imprime o array direto, gerando link vazio ou a palavra 'Array' no download.
- O upload_max_filesize ou o post_max_size do PHP no servidor é menor que o arquivo enviado, então o PHP corta o upload antes mesmo de o ACF validar o campo.

## Como resolver

1. Revise Allowed file types e os limites de tamanho do campo: Em ACF, abra o grupo de campos e edite o File Field. Confirme se Allowed file types está vazio (aceita todos) ou inclui a extensão que você precisa enviar, e verifique se Minimum e Maximum não estão rejeitando o arquivo por tamanho.

```
Painel WP -> ACF -> Grupos de Campos -> abra o grupo e edite o File Field
Deixe 'Allowed file types' vazio ou inclua a extensão (ex.: pdf,zip,docx)
Confira 'Minimum' e 'Maximum' (aceita MB ou strings como '400 KB')
```

2. Libere o tipo MIME no WordPress se a extensão for bloqueada: Se o aviso for 'this file type is not permitted', o bloqueio é do núcleo do WordPress, não do ACF. Para extensões legítimas que não estão na allowlist padrão, registre o tipo MIME pelo filtro upload_mimes (código abaixo) ou habilite o tipo de forma controlada.

```
Edite o functions.php do tema filho (via FTP ou editor de tema)
Adicione o filtro 'upload_mimes' liberando apenas a extensão necessária
Reenvie o arquivo e confirme que a mídia aceita o tipo
```

3. Ajuste a opção Library para liberar a Biblioteca de Mídia: Se arquivos existentes não aparecem para seleção, a opção Library está restrita ao post. Mude para 'All' para permitir escolher qualquer item já enviado à Biblioteca de Mídia.

```
Painel WP -> ACF -> Grupos de Campos -> edite o File Field
Defina a opção 'Library' como 'All' (em vez de 'Uploaded to post')
Salve o grupo de campos e recarregue o editor do post
```

4. Alinhe o template ao Return Format do campo: Quando o arquivo salva mas o download quebra, o Return Format diverge do código. Confirme o Return Format em Return value e leia o valor de acordo: array usa $file['url'], URL usa the_field direto, e ID usa wp_get_attachment_url para gerar o link.

```
Painel WP -> ACF -> edite o File Field -> 'Return value' (Return Format)
File Array: leia $file['url'] e $file['filename']
File URL: imprima the_field('arquivo') direto no href
File ID: gere a URL com wp_get_attachment_url( $id )
```

5. Aumente os limites de upload do PHP no servidor: Se o erro for de upload_max_filesize ou o envio cortar em arquivos grandes, o limite é do PHP. Ajuste upload_max_filesize e post_max_size para um valor acima do arquivo, pelo painel da hospedagem ou no php.ini.

```
No painel da hospedagem, localize a configuração de PHP do site
Aumente 'upload_max_filesize' (ex.: 64M) e 'post_max_size' (ex.: 64M)
Painel WP -> Ferramentas -> Saúde do site -> Informações -> confira os novos limites
```


## Código

```php
<?php
// 1) Libera uma extensao MIME especifica (ex.: webp) no upload do WordPress.
add_filter( 'upload_mimes', 'full_acf_allow_mime' );
function full_acf_allow_mime( $mimes ) {
    $mimes['webp'] = 'image/webp';
    return $mimes;
}

// 2) Renderiza o download conforme o Return Format do File Field.
$file = get_field( 'arquivo' );
if ( $file ) {
    if ( is_array( $file ) ) {            // Return Format = File Array
        $url   = $file['url'];
        $label = $file['filename'];
    } elseif ( is_numeric( $file ) ) {    // Return Format = File ID
        $url   = wp_get_attachment_url( $file );
        $label = get_the_title( $file );
    } else {                              // Return Format = File URL
        $url   = $file;
        $label = basename( $file );
    }
    printf(
        '<a href="%s" download>%s</a>',
        esc_url( $url ),
        esc_html( $label )
    );
}
```

## Perguntas frequentes

### Por que o ACF recusa meu arquivo com 'this file type is not permitted'

Esse aviso vem do próprio WordPress, não do ACF. A extensão não está na lista de tipos MIME permitidos pelo núcleo. Confirme primeiro o campo Allowed file types do File Field e, se a extensão for legítima, libere o tipo MIME pelo filtro upload_mimes no tema.

### O File Field salva mas o link de download aparece vazio. O que houve

Quase sempre o Return Format diverge do template. Se o campo retorna File Array, leia $file['url']; se retorna File URL, imprima the_field direto; se retorna File ID, gere a URL com wp_get_attachment_url. Imprimir o valor errado deixa o href vazio ou mostra a palavra Array.

### Qual a diferença entre File Array, File URL e File ID no Return value

Segundo a documentação do ACF, File Array retorna um array com url, filename, title e outros dados; File URL retorna só a string da URL; e File ID retorna o inteiro do attachment. Cada formato exige uma leitura diferente com get_field no template.

### Por que arquivos da Biblioteca de Mídia não aparecem para selecionar no campo

A opção Library do campo provavelmente está como 'Uploaded to post', que limita a seleção aos arquivos enviados àquele post. Mude para 'All' nas configurações do File Field para liberar toda a Biblioteca de Mídia.

### O upload corta em arquivos grandes mesmo dentro do limite do campo

Nesse caso o limite é do servidor, não do ACF. Os valores upload_max_filesize e post_max_size do PHP precisam ser maiores que o arquivo. Ajuste-os no painel da hospedagem ou no php.ini e confira o resultado em Saúde do site.

### Como restringir os tipos de arquivo que o File Field aceita

Use o campo Allowed file types do File Field e informe uma lista separada por vírgula, como pdf,zip,docx. Deixar vazio aceita todos os tipos. Limitar às extensões esperadas evita uploads indevidos e reduz risco de segurança.

### Preciso de código para exibir o arquivo do File Field no frontend

Depende do Return Format. Com File URL dá para imprimir the_field direto no href sem lógica extra. Com File Array ou File ID você lê o valor com get_field e monta o link, usando wp_get_attachment_url no caso do ID.

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