Options Page ACF Não Salva: como corrigir o erro

Tipo Page Builders

Nome do erro Options Page do ACF PRO não salva EN: ACF PRO Options Page not saving

Severidade Grave

Descrição A Options Page do ACF PRO que não salva acontece quando você clica em Update e os valores voltam vazios, quase sempre porque a página foi registrada com um post_id diferente do que o get_field lê, a capability barra a gravação ou o field group não tem a location rule de Options Page.

O que é Options Page ACF que não salva?

A Options Page do ACF PRO é uma tela de configurações global, criada com acf_add_options_page(), que guarda valores na tabela wp_options em vez de em um post. O erro de não salvar é quando você preenche os campos, clica em Update e, ao recarregar, os campos voltam em branco ou o frontend lê vazio com get_field, mesmo sem nenhuma mensagem fatal. O ponto central é o post_id da tela: na gravação o ACF usa o post_id definido no registro da página (option por padrão), e na leitura o tema precisa pedir exatamente o mesmo identificador. Quando esses dois lados divergem, ou quando a capability impede o POST de Update, o valor é gravado em um lugar e lido em outro, dando a impressão de que a página não salva nada.

Como identificar

Você preenche a Options Page, clica em Update e, ao recarregar a tela, todos os campos voltam em branco.
O frontend imprime vazio em get_field(‘campo’, ‘option’), mesmo com o valor aparentemente salvo no painel.
A barra do topo mostra a mensagem Options Updated em verde, mas nada persiste depois do reload.
var_dump( get_field(‘campo’, ‘option’) ) devolve bool(false) na tela de opções e no tema.
Em sites com várias Options Pages, o valor de uma tela aparece em outra, ou some ao trocar de aba.

Como prevenir

Defina um post_id explícito e único no acf_add_options_page() de cada tela e use o mesmo identificador em toda chamada de get_field e the_field do tema.
Registre todas as Options Pages dentro do hook acf/init para que carreguem na ordem certa em qualquer versão do WordPress.
Dê um field group próprio para cada Options Page, evitando que duas telas compartilhem campos e sobrescrevam valores.
Defina a capability igual ao papel real de quem vai editar a tela, em vez de deixar o padrão edit_posts quando só administradores deveriam gravar.

Causa

A página foi registrada com um post_id customizado no acf_add_options_page(), por exemplo opções_tema, mas o tema lê com get_field('campo', 'option'); como os dois identificadores não batem, o valor é gravado em um registro de wp_options e lido de outro.
A capability definida no registro da página é maior que a do usuário (o padrão é edit_posts); o usuário vê a tela mas o WordPress recusa o POST de Update, então o save retorna sem gravar.
O field group não tem a location rule Options Page ativa apontando para essa tela, então os campos aparecem mas não são vinculados ao salvamento daquela página.
A chamada acf_add_options_page() roda fora do hook acf/init (ou depois do admin_menu na prioridade 99); no WordPress 6.8 ou superior isso gera notice de tradução precoce e a página não registra corretamente.
Duas Options Pages compartilham o mesmo field group sem post_id próprio, então os valores sincronizam ou se sobrescrevem entre as telas em vez de salvar isolados.
O autoload do valor está true e há cache de objeto persistente (Redis ou Memcached) servindo a versão antiga de wp_options, então o save grava mas a leitura entrega o cache anterior.

Como resolver

Confirme o post_id real da página e da leitura: Abra o arquivo onde a página é registrada e anote o valor do post_id. Esse identificador é o que o ACF usa para gravar. Em seguida imprima a leitura no template para ver de onde o tema busca o valor. Se os dois forem diferentes, é a causa do save fantasma.
```
acf_add_options_page( array( 'post_id' => 'opções_tema' ) );
var_dump( get_field( 'telefone', 'opções_tema' ) );
```
Alinhe a leitura ao mesmo post_id do registro: Padronize o segundo parâmetro de get_field e the_field para usar exatamente o post_id da página. Se você manteve o padrão da página, use a string option; se definiu um post_id customizado no registro, use o mesmo valor na leitura.
```
the_field( 'telefone', 'option' );
$tel = get_field( 'telefone', 'opções_tema' );
```
Ajuste a capability para permitir a gravação: Se o usuário vê a tela mas o Update não persiste, a capability do registro está acima do papel dele. Baixe para uma capacidade que o usuário tenha, como manage_options para administrador, e teste o save de novo.
```
acf_add_options_page( array( 'capability' => 'manage_options' ) );
```
Ative a location rule Options Page no field group: No painel do ACF, abra o field group e confirme que a regra de localização aponta para a Options Page certa. Sem essa regra os campos aparecem mas não são salvos junto da página. Caminho no menu: Custom Fields -> Field Groups -> seu grupo -> Settings -> Location.
```
Custom Fields -> Field Groups -> [grupo] -> Settings -> Location
Show this field group if: Options Page -> is equal to -> [sua página]
```
Registre a página dentro do hook acf/init: Mova a chamada acf_add_options_page() para dentro de uma função enganchada em acf/init. Isso evita o notice de tradução precoce do WordPress 6.8 e garante que a página registre antes do admin_menu na prioridade 99.
```
add_action( 'acf/init', 'minha_options_page' );
function minha_options_page() { acf_add_options_page(); }
```
Limpe o cache de objeto se o valor persiste antigo: Se o banco já tem o valor novo mas a tela ainda mostra o antigo, um cache de objeto persistente está servindo wp_options desatualizado. Esvazie o cache por WP-CLI e recarregue a página de opções.
```
wp cache flush
```

PHP

<?php
// Registro robusto de uma Options Page do ACF PRO que salva de forma confiavel.
add_action( 'acf/init', 'full_register_options_page' );
function full_register_options_page() {
    if ( ! function_exists( 'acf_add_options_page' ) ) {
        return;
    }
    acf_add_options_page( array(
        'page_title' => 'Opções do Tema',
        'menu_slug'  => 'opcoes-tema',
        'capability' => 'manage_options', // papel que pode gravar
        'post_id'    => 'opcoes_tema',     // mesmo id usado na leitura
        'autoload'   => true,
    ) );
}

// Leitura no template usando exatamente o mesmo post_id do registro.
$telefone = get_field( 'telefone', 'opcoes_tema' );
if ( $telefone ) {
    echo esc_html( $telefone );
}

Perguntas frequentes

Por que a Options Page do ACF mostra Options Updated mas não salva?

A mensagem verde confirma que o POST chegou, não que o valor foi lido de volta. Quase sempre o post_id do registro difere do post_id da leitura, então o ACF grava em um registro de wp_options e o tema busca de outro. Alinhe os dois identificadores.

Devo usar option ou um post_id customizado na Options Page?

Os dois funcionam, desde que registro e leitura usem o mesmo. Se você manteve o padrão, leia com get_field('campo', 'option'). Se definiu post_id no acf_add_options_page(), use exatamente esse valor na leitura, senão o campo volta vazio.

A capability pode impedir o save da Options Page?

Sim. Se a capability do registro for maior que a do usuário, ele vê a tela mas o WordPress recusa o POST de Update. O padrão é edit_posts; para telas só de administrador use manage_options e confirme que o usuário tem esse papel.

Por que duas Options Pages mostram os mesmos valores?

Elas compartilham o mesmo field group sem post_id próprio, então os valores sincronizam entre as telas. Crie um field group separado por página ou defina post_id distinto em cada acf_add_options_page() para isolar os dados.

Preciso registrar a Options Page dentro de algum hook?

Sim. Chame acf_add_options_page() dentro do hook acf/init e antes do admin_menu na prioridade 99. No WordPress 6.8 ou superior, registrar fora desse hook gera notice de tradução precoce e a página pode não registrar.

O valor salva no banco mas a tela continua vazia, o que é?

Um cache de objeto persistente, como Redis ou Memcached, está servindo a versão antiga de wp_options. Rode wp cache flush e recarregue. Se persistir, confira se o autoload do valor está coerente com o uso da página.

A location rule do field group afeta o salvamento?

Afeta. Se a regra de localização não aponta para a Options Page, os campos aparecem mas não ficam vinculados ao save daquela tela. Em Custom Fields, abra o grupo e ajuste a regra para Options Page is equal to a sua página.

Grave

Como corrigir o Listing Grid vazio no JetEngine

O Listing Grid vazio no JetEngine ocorre quando a query (Post Status, Meta Query, Tax Query, Offset ou Cache Query) não retorna nenhum item para o Listing template. Corrige-se alinhando os parametros do Query Builder a dados que existem no site.

Atenção

Como corrigir o widget Woo Product Grid no Essential Addons

O erro do Woo Product Grid no Essential Addons acontece quando o widget fica vazio, mostra a mensagem de nenhum produto encontrado ou quebra no Elementor porque o WooCommerce esta inativo, não ha produtos publicados que casem com a consulta, ou o elemento WooCommerce do Essential Addons não esta habilitado.

Atenção

Como corrigir o Clone Field que não duplica campos no ACF PRO

O Clone Field do ACF PRO não duplica campos quando dois clones do mesmo grupo compartilham o field_key, quando o Display está como Group sem prefixo de nome, ou quando o grupo clonado original está inativo, fazendo os campos sumirem ou não salvarem.

Atenção

Como corrigir o Mini Cart que não exibe corretamente no Astra Pro com WooCommerce

O Astra mini cart do WooCommerce que não aparece deixa o icone ausente no header, abre um dropdown vazio ou exibe a janela transparente. A causa quase sempre e o elemento Cart não adicionado no Header Builder, o script wc-cart-fragments bloqueado pelo cache, ou o filtro de fundo do outline cart desligado após migrar do header antigo.

Atenção

Como corrigir o Maps Listing do JetEngine que não exibe marcadores no WordPress

O JetEngine não exibe marcadores no Maps Listing quando falta uma API key válida do provedor de mapas, quando o campo de endereço não tem coordenadas geocodificadas, ou quando a fonte de endereço do widget aponta para o campo errado. Sem latitude e longitude armazenadas, o mapa carrega mas nenhum pino é desenhado.

Atenção

Como corrigir o Taxonomy Field que não salva termos no ACF PRO

O ACF Taxonomy Field não salva termos quando a opção Save Terms está desligada: por padrão ela vem desativada, então o campo guarda a seleção apenas como metadado e nunca conecta o termo ao post na taxonomia.

Setores

Extensões

Integrações

Como corrigir a Options Page que não salva no ACF PRO

O que é Options Page ACF que não salva?

Como identificar

Como prevenir

Causa

Como resolver

Perguntas frequentes

Itens relacionados

Como corrigir o Listing Grid vazio no JetEngine

Como corrigir o widget Woo Product Grid no Essential Addons

Como corrigir o Clone Field que não duplica campos no ACF PRO

Como corrigir o Mini Cart que não exibe corretamente no Astra Pro com WooCommerce

Como corrigir o Maps Listing do JetEngine que não exibe marcadores no WordPress

Como corrigir o Taxonomy Field que não salva termos no ACF PRO

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