ACF Custom Fields não aparecem no frontend: como corrigir

Tipo Page Builders

Nome do erro Custom Fields do ACF PRO não exibem no frontend EN: ACF PRO custom fields not showing on frontend

Severidade Grave

Descrição Quando os ACF custom fields não aparecem no frontend, o valor existe no banco mas o tema chama o campo de forma incorreta: nome errado, fora do Loop, sem post ID ou com Location Rules que não casam com a tela atual. A correção é alinhar a chamada the_field() ou get_field() ao contexto real do template.

O que é ACF custom fields que não aparecem no frontend?

ACF custom fields que não aparecem no frontend é a situação em que um campo do Advanced Custom Fields PRO foi preenchido no editor do WordPress, mas o valor não é renderizado na página pública. Na maioria dos casos o dado está salvo corretamente no postmeta; o que falha é a forma como o tema solicita esse valor com as funções the_field() ou get_field(). O ACF só retorna o valor quando a função recebe o nome exato do campo e sabe a qual post ele pertence.

O problema também aparece quando o grupo de campos (Field Group) tem Location Rules que não correspondem à tela onde você está editando ou exibindo. Se o grupo está restrito a um post type ou template que não é o atual, o campo nem é carregado para aquele contexto, e a função do tema devolve um valor vazio.

Como identificar

A página pública mostra um espaço em branco ou nada no lugar onde o campo deveria aparecer, mesmo com o valor preenchido no admin.
Ao usar var_dump(get_field(‘nome_do_campo’)) no template, o retorno é exatamente “bool(false)” ou “NULL”.
O campo aparece corretamente no editor do post, mas some no tema (single.php, page.php ou template do page builder).
Com WP_DEBUG ativo, surge “Notice: Trying to get property of non-object” ou “Undefined variable” na linha que chama the_field().
O shortcode [acf field=”nome_do_campo”] renderiza vazio dentro de um conteúdo ou widget.

Como prevenir

Padronize os nomes dos campos em minúsculas com underscore e copie o Field Name direto do painel ao escrever o template, evitando erros de digitação.
Sempre que chamar get_field() fora do Loop, passe explicitamente o post ID ou ‘option’ como segundo parâmetro.
Antes de publicar, valide cada novo campo com var_dump no template e WP_DEBUG ativo em ambiente de staging.
Documente o Return Format de cada campo de imagem ou link no Field Group para que o time saiba se deve ecoar a URL ou tratar o array.

Causa

A função do tema usa o field key (formato field_5f8a1b2c3d4e) em vez do field name legível; the_field() e get_field() esperam o nome do campo, não a chave.
A chamada the_field() ou get_field() está fora do The Loop e sem o segundo parâmetro de post ID, então o ACF não sabe de qual post buscar o valor e retorna false.
As Location Rules do Field Group apontam para outro post type, template ou taxonomia, de modo que o grupo não é atribuído à tela atual e o campo não existe naquele contexto.
O nome do campo na função não bate com o nome real cadastrado no Field Group (diferença de underscore, acento, maiúscula ou plural, como meu_campo versus meucampo).
O Return Format do campo está como Array ou Image Array, então the_field() imprime vazio porque tenta ecoar uma estrutura em vez de uma string de texto ou URL.
O valor está em um post diferente (por exemplo um Options Page ou outro post ID) e a função foi chamada sem informar 'option' ou o ID correto como segundo argumento.

Como resolver

Confirme se o valor está salvo no banco com var_dump: No template do tema (por exemplo single.php), antes de qualquer formatação, imprima o valor cru do campo. Se o retorno for false ou NULL, o problema é de contexto ou de nome; se vier o valor, o problema é só de formatação na exibição. Ative WP_DEBUG no wp-config.php para ver os avisos.
```
var_dump( get_field('nome_do_campo') );
```
Use o nome do campo, não o field key: Abra Custom Fields, edite o Field Group e confira o valor exato em Field Name (coluna do meio, em minúsculas com underscore). Use esse nome na função, nunca a string que começa com field_. O nome é o identificador legível; a chave field_ é interna do ACF.
```
the_field('preco_promocional');
```
Garanta o contexto do post passando o post ID: Se a chamada está fora do Loop (em um header, sidebar, footer ou template de page builder), informe o post ID como segundo parâmetro. Para campos de uma Options Page, passe a string 'option'. Isso elimina o retorno false por falta de contexto.
```
$preco = get_field('preco_promocional', get_the_ID());
$logo = get_field('logo_rodape', 'option');
```
Revise as Location Rules do Field Group: Em Custom Fields, edite o grupo e role até Settings -> Location. Confirme que a regra (Post Type igual a, Page Template igual a, Taxonomy etc.) corresponde exatamente à tela onde o campo deve aparecer. Se o grupo aponta para outro contexto, o campo não é atribuído à página atual e nunca retorna valor. Confirme também que o grupo está Ativo (Active).
Ajuste o Return Format conforme o tipo de campo: Para campos Image, Link ou Post Object, the_field() pode imprimir vazio quando o Return Format é Array. Defina o Return Format como URL ou ID quando quiser ecoar direto, ou use get_field() e acesse a chave do array no tema. Salve o Field Group após a mudança.
```
$img = get_field('imagem_destaque');
echo esc_url( $img['url'] );
```

PHP

<?php
// Exibir um campo ACF com segurança, dentro ou fora do Loop.
// Passa o post ID explicitamente para evitar retorno false fora do Loop.

$post_id = get_the_ID();
$subtitulo = get_field( 'subtitulo', $post_id );

if ( $subtitulo ) {
    echo '<p class="subtitulo">' . esc_html( $subtitulo ) . '</p>';
}

// Campo de imagem com Return Format = Array: acessar a chave 'url'.
$imagem = get_field( 'imagem_destaque', $post_id );

if ( $imagem && ! empty( $imagem['url'] ) ) {
    echo '<img src="' . esc_url( $imagem['url'] ) . '" alt="' . esc_attr( $imagem['alt'] ) . '">';
}

// Campo global de uma Options Page: usar 'option' como segundo argumento.
$telefone = get_field( 'telefone_contato', 'option' );

if ( $telefone ) {
    echo '<span class="tel">' . esc_html( $telefone ) . '</span>';
}
?>

Perguntas frequentes

Por que get_field() retorna false mesmo com o campo preenchido?

Quase sempre é contexto ou nome. Se a chamada está fora do Loop, o ACF não sabe de qual post buscar e devolve false; passe o post ID como segundo parâmetro. Se o nome do campo difere do cadastrado no Field Group, o retorno também é false. Confirme com var_dump antes de formatar.

Qual a diferença entre the_field() e get_field() no ACF?

the_field() imprime o valor direto na página, ideal para texto simples. get_field() retorna o valor como variável, para você tratar, validar ou escapar antes de exibir. Para imagens, links e relacionamentos use get_field() e trabalhe o array ou a URL retornada.

Devo usar o field name ou o field key na função do tema?

Use o field name, o identificador legível em minúsculas com underscore que aparece na coluna Field Name do grupo. A field key, que começa com field_ seguido de caracteres aleatórios, é de uso interno do ACF e faz the_field() e get_field() retornarem vazio quando usada no tema.

Por que o campo aparece no admin mas some no frontend?

O valor está salvo, então o problema é a chamada no template. Verifique se o nome do campo está correto, se a função está dentro do Loop ou recebe o post ID, e se as Location Rules do Field Group casam com o template que renderiza essa página. Um único desses fatores fora do lugar zera a saída.

Como exibir um campo do ACF dentro de um header ou sidebar?

Header, sidebar e footer rodam fora do Loop principal, então a função não tem contexto de post. Passe o ID explicitamente, por exemplo get_field('subtitulo', get_the_ID()), ou use get_queried_object_id() para a página atual. Para campos globais, use uma Options Page e passe 'option' como segundo argumento.

Por que um campo de imagem do ACF imprime vazio com the_field()?

Campos Image costumam ter Return Format definido como Array, e the_field() não consegue ecoar uma estrutura como string. Mude o Return Format para URL ou ID no Field Group, ou use get_field() e acesse a chave url do array antes de exibir com esc_url.

Preciso ativar WP_DEBUG para resolver campos vazios do ACF?

Ajuda muito. Com WP_DEBUG em true no wp-config.php, o WordPress mostra avisos como Trying to get property of non-object na linha exata da chamada, apontando se o campo retorna null ou se você está acessando um array como string. Use apenas em staging, nunca em produção.

As Location Rules afetam se o campo aparece no frontend?

Sim, de forma indireta. As Location Rules determinam a quais telas o Field Group é atribuído. Se a regra aponta para um post type ou template diferente do atual, o campo nem é carregado naquele contexto e a função do tema retorna vazio, mesmo que o nome esteja correto.

Atenção

Como corrigir o conflito de Meta Boxes entre ACF PRO e JetEngine no WordPress

O conflito de meta boxes entre ACF PRO e JetEngine acontece quando os dois plugins registram grupos de campos para o mesmo tipo de post e gravam na mesma meta key, gerando caixas duplicadas no editor, valores sobrescritos e campos que parecem não salvar.

Atenção

Como corrigir WPBakery com shortcodes quebrados

WPBakery com shortcodes quebrados mostra códigos crus como [vc_row] e [vc_column] no lugar do layout montado, porque o plugin que interpreta esses shortcodes não esta ativo ou registrado. A causa quase sempre e o WPBakery (Visual Composer) desativado, embutido num tema que sumiu, ou páginas migradas para um site sem o plugin.

Atenção

Como corrigir o widget Data Table que não carrega dados no Essential Addons

O Essential Addons Data Table não carrega dados quando o widget está desativado em Essential Addons > Elements, quando a integração externa (Google Sheets, TablePress ou Ninja Tables) está mal configurada, ou quando o cache serve uma versão antiga da tabela sem o conteúdo.

Atenção

Como corrigir os Data Stores do JetEngine que não salvam dados do usuário no WordPress

O JetEngine Data Stores não salva quando o tipo de armazenamento escolhido é por sessao do navegador (Local Storage ou Cookies) e o visitante troca de dispositivo ou limpa o navegador, ou quando o tipo Users esta em uso mas o visitante não esta logado, fazendo os itens adicionados sumirem ao recarregar a página.

Atenção

Como corrigir Elementor com widgets que não aparecem

O Elementor com widgets que não aparecem mostra o painel lateral vazio ou sem os widgets esperados, e elementos somem da página ao editar. A causa quase sempre e o JavaScript do editor bloqueado por minificacao ou cache, o Elementor PRO inativo (escondendo os widgets PRO), ou memória PHP insuficiente impedindo o painel de montar a lista.

Grave

Como corrigir o JetSmartFilters AJAX que não retorna resultados

O JetSmartFilters AJAX que não retorna resultados aplica o filtro, dispara a chamada ao admin-ajax.php, mas o Listing Grid volta vazio ou sem mudar. A causa quase sempre e o Query ID do filtro diferente do provider, o indexer não gerado, ou o cache servindo a página antiga.

Setores

Extensões

Integrações

Como corrigir Custom Fields que não exibem no frontend no ACF PRO

O que é ACF custom fields que não aparecem no frontend?

Como identificar

Como prevenir

Causa

Como resolver

Perguntas frequentes

Itens relacionados

Como corrigir o conflito de Meta Boxes entre ACF PRO e JetEngine no WordPress

Como corrigir WPBakery com shortcodes quebrados

Como corrigir o widget Data Table que não carrega dados no Essential Addons

Como corrigir os Data Stores do JetEngine que não salvam dados do usuário no WordPress

Como corrigir Elementor com widgets que não aparecem

Como corrigir o JetSmartFilters AJAX que não retorna resultados

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