ACF File Field upload não funciona: como corrigir

Tipo Page Builders

Nome do erro Upload do File Field do ACF PRO não funciona EN: ACF PRO File Field upload not working

Severidade Atenção

Descrição 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.

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

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')
```
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
```
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
```
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 )
```
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
```

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.

Atenção

Como corrigir o erro do Image Grid no Happy Addons

O erro do Image Grid no Happy Addons acontece quando o widget está desativado no Feature Controller, o Elementor está desatualizado ou um cache antigo serve o CSS e o JavaScript errados, fazendo o widget sumir do editor, as imagens não aparecerem ou o layout masonry quebrar.

Atenção

Como corrigir o JetReviews que não carrega avaliações no frontend

O JetReviews não carrega avaliação no frontend quando o widget de avaliações não foi inserido no template do post, quando as avaliações ficam presas na moderação ou quando o cache da página serve uma versão antiga sem as notas mais recentes.

Grave

Como corrigir o JetEngine Relations que não conecta posts

JetEngine Relations que não conecta posts quase sempre vem dos controles do objeto parent ou child desligados na relação, do post type não bater com o objeto escolhido, ou do post não ser salvo com Atualizar após a conexão. Ativar os controles e salvar resolve.

Crítico

Como corrigir Elementor que não salva alterações

O Elementor que não salva alterações deixa o botão Atualizar girando para sempre ou retorna erro, e o trabalho se perde ao recarregar. A causa quase sempre é o max_input_vars do PHP baixo demais para a página, ou uma regra de mod_security/WAF bloqueando a requisição de salvamento (admin-ajax.php).

Informativo

Como corrigir o Lightbox da Image Gallery no Ultimate Addons

O Lightbox da Image Gallery do Ultimate Addons para de abrir quando o Click Action do widget não está configurado como Lightbox, quando outro lightbox concorrente ou a otimização de JavaScript de um plugin de cache bloqueiam o script que monta o popup.

Atenção

Como corrigir o erro do widget Advanced Accordion no Essential Addons

O Essential Addons accordion não funciona quando o elemento Advanced Accordion esta desativado na tela de Elementos do plugin, quando ha conflito com cache ou JavaScript de outro plugin, ou quando o Essential Addons e o Elementor estão desatualizados, impedindo o widget de aparecer no editor ou de abrir no frontend.

Setores

Extensões

Integrações

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

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

Como identificar

Como prevenir

Causa

Como resolver

Perguntas frequentes

Itens relacionados

Como corrigir o erro do Image Grid no Happy Addons

Como corrigir o JetReviews que não carrega avaliações no frontend

Como corrigir o JetEngine Relations que não conecta posts

Como corrigir Elementor que não salva alterações

Como corrigir o Lightbox da Image Gallery no Ultimate Addons

Como corrigir o erro do widget Advanced Accordion no Essential Addons

Setores

Extensões

Integrações

Extensões

Hero Sections

Seções de CTA

Login

Blog

Cabeçalhos

Seções de FAQ

Cadastro

Blog individual

Rodapés

Seções de contato

Seções de preços

Faixas

Portfólio

Seções de equipe

Números

Logotipos