ACF Taxonomy Field não salva termos: como corrigir

Tipo Page Builders

Nome do erro Taxonomy Field não salva os termos no post EN: ACF Taxonomy Field not saving terms

Severidade Atenção

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

O que é ACF Taxonomy Field que não salva termos?

O ACF Taxonomy Field é o tipo de campo do Advanced Custom Fields que permite selecionar um ou mais termos de uma taxonomia ao editar um post. Ele pode aparecer como checkbox, multi select, botões de rádio ou um campo select, e devolve o termo escolhido como objeto WP_Term ou como ID, conforme a opção Return Value. Por padrão, esse campo apenas registra a escolha como valor próprio do ACF (um metadado do post), sem mexer nas relações reais de taxonomia do WordPress.

É aqui que mora a confusão de quem diz que o campo não salva. Segundo a documentação oficial do ACF, conectar de fato o termo ao post depende da opção Save Terms, que vem desativada por padrão (Defaults to off). Sem ela ligada, o termo selecionado não passa a integrar a taxonomia do post: ele não aparece na coluna da lista de posts, não filtra arquivos por categoria nem alimenta consultas por taxonomia. O campo guardou a seleção do seu jeito, mas para o WordPress o post continua sem aquele termo.

Como identificar

O termo selecionado no campo some ao recarregar a tela de edição, porque a opção Load Terms está desligada e o ACF não recarrega a seleção a partir da taxonomia do post.
O post não aparece na listagem da taxonomia (por exemplo, no arquivo da categoria ou tag) mesmo com o termo escolhido no campo ACF.
A coluna da taxonomia na tela ‘Todos os posts’ fica vazia para o post, apesar de o campo Taxonomy Field mostrar um termo selecionado.
Uma consulta WP_Query com tax_query por aquele termo não retorna o post, sinal de que a relação termo-post nunca foi gravada.
Ao escolher ‘Adicionar novo termo’ pelo campo, o termo é criado na taxonomia mas não fica vinculado ao post depois de salvar.

Antes de começar: Antes de mexer nas opções do campo em produção ou adicionar qualquer snippet ao site, faça um backup do banco de dados e dos arquivos, ou teste primeiro em um ambiente de staging, para poder reverter caso a atribuição de termos saia errada nos posts existentes.

Como prevenir

Ao criar um Taxonomy Field, defina logo se ele deve gravar na taxonomia: ligue Save Terms e Load Terms juntos quando o objetivo for conectar o termo ao post de verdade.
Documente, para cada Taxonomy Field, qual taxonomia ele usa e em quais post types ela está registrada, evitando campos apontando para taxonomias incompatíveis.
Padronize quem pode atribuir termos definindo a capability assign_terms nos papéis certos, para que editores consigam salvar a seleção.
Ao usar hooks acf/save_post próprios, ajuste a prioridade para não sobrescrever os termos que o ACF acabou de gravar.

Causa

A opção Save Terms do campo está desativada: na documentação oficial do ACF ela 'conecta os termos selecionados ao post' e vem desligada por padrão, então sem ligá-la a seleção fica só como valor do ACF e nunca entra na taxonomia do post.
A opção Load Terms está desativada, o que faz a seleção parecer perdida ao reabrir o post, porque o ACF não recarrega os termos a partir das relações de taxonomia gravadas no post.
A taxonomia escolhida no campo não está registrada para o tipo de post sendo editado, então mesmo com Save Terms ligado o WordPress não mantém a relação entre aquele post e o termo.
Um hook acf/save_post de outro plugin ou do tema roda com prioridade que sobrescreve ou reverte os termos logo após o ACF gravar, desfazendo a conexão recém-criada.
O usuário que edita o post não tem a capability assign_terms daquela taxonomia, fazendo o WordPress descartar a atribuição do termo no momento de salvar.

Como resolver

Ative a opção Save Terms no campo: Abra o grupo de campos no ACF, edite o Taxonomy Field e ligue a opção Save Terms. Segundo a documentação oficial, ela conecta os termos selecionados ao post e vem desativada por padrão, sendo a causa número um de o termo não ser gravado na taxonomia.
```
Painel WP -> ACF -> Grupos de Campos -> abra o grupo e edite o Taxonomy Field
Marque a opção Save Terms (Connect selected terms to the post)
Salve o grupo de campos e edite um post de teste para confirmar
```
Ative a opção Load Terms para recarregar a seleção: Ainda na edição do campo, ligue Load Terms para que o ACF leia os termos já vinculados ao post e mostre a seleção correta ao reabrir a tela, evitando a impressão de que o campo perdeu o valor.
```
Painel WP -> ACF -> Grupos de Campos -> edite o Taxonomy Field
Marque a opção Load Terms (Load value from post terms)
Salve e recarregue um post para confirmar que a seleção persiste
```
Confira a taxonomia e o tipo de post do campo: Verifique se a taxonomia escolhida na opção Taxonomy do campo está realmente registrada para o tipo de post que você edita. Se a taxonomia não atende aquele post type, o WordPress não mantém a relação mesmo com Save Terms ligado.
```
Painel WP -> ACF -> edite o Taxonomy Field -> confira o seletor Taxonomy
Confirme em qual post type a taxonomia foi registrada (register_taxonomy)
Ajuste a regra de Localizacao do grupo para casar com esse post type
```
Cheque a capability assign_terms do usuário: Confirme se o papel do usuário que edita o post tem permissão de atribuir termos da taxonomia. Sem a capability assign_terms, o WordPress descarta a atribuição ao salvar e o campo parece não gravar.
```
Painel WP -> Usuários -> confira o papel (role) de quem edita o post
Garanta que o papel possui a capability assign_terms da taxonomia
Teste salvando o post com um usuário administrador para isolar permissão
```
Isole conflito de hook acf/save_post: Se o termo ainda some após salvar, desative os demais plugins um a um e troque para um tema padrão. Um hook acf/save_post de outro plugin ou do tema pode reverter os termos logo depois que o ACF grava.
```
Painel WP -> Plugins -> desative os demais plugins um a um
Painel WP -> Aparencia -> Temas -> ative um tema padrão para teste
Salve o post a cada teste até identificar o que reverte os termos
```

PHP

<?php
add_action( 'acf/save_post', 'full_sync_acf_taxonomy_terms', 20 );
function full_sync_acf_taxonomy_terms( $post_id ) {
    // Roda apos o ACF gravar; ignora autosave e revisoes.
    if ( wp_is_post_autosave( $post_id ) || wp_is_post_revision( $post_id ) ) {
        return;
    }
    $field_name = 'minha_taxonomia';   // nome do Taxonomy Field
    $taxonomy   = 'category';          // slug da taxonomia
    $terms = get_field( $field_name, $post_id );
    if ( empty( $terms ) ) {
        return;
    }
    // Normaliza para IDs (Return Value pode ser objeto ou ID).
    $term_ids = array_map( function ( $t ) {
        return is_object( $t ) ? (int) $t->term_id : (int) $t;
    }, (array) $terms );
    wp_set_object_terms( $post_id, $term_ids, $taxonomy, false );
}

Perguntas frequentes

Por que o ACF Taxonomy Field não salva os termos no post

Porque a opção Save Terms do campo vem desativada por padrão. A documentação oficial do ACF diz que ela conecta os termos selecionados ao post; sem ligá-la, a seleção fica só como valor do ACF e nunca entra na taxonomia do post. Edite o campo e marque Save Terms.

Para que serve a opção Save Terms do Taxonomy Field

A opção Save Terms conecta os termos selecionados ao post, gravando a relação real na taxonomia do WordPress. Com ela desligada, o ACF guarda a escolha apenas como metadado próprio e o post não passa a integrar aquele termo na taxonomia.

Qual a diferença entre Save Terms e Load Terms no ACF

Save Terms grava os termos selecionados na taxonomia do post ao salvar. Load Terms faz o caminho inverso: carrega a seleção a partir dos termos já vinculados ao post quando você reabre a edição. As duas vêm desativadas por padrão e costumam ser usadas juntas.

O termo some quando recarrego a tela de edição do post

Isso costuma acontecer quando Load Terms está desligado: o ACF não recarrega a seleção a partir dos termos do post. Ligue Load Terms para o campo ler de novo os termos já vinculados e exibir a seleção corretamente ao reabrir o post.

Preciso de código para o Taxonomy Field gravar os termos

Não para o caso comum. Basta ligar Save Terms e Load Terms nas opções do campo. Código só é necessário se você quiser forçar ou customizar a gravação em casos específicos, como sincronizar termos por um hook acf/save_post próprio.

O Taxonomy Field cria termos novos na taxonomia

Sim, se a opção Create Terms estiver habilitada o campo permite adicionar novos termos pela tela de edição. Mas vincular esse termo ao post ainda depende de Save Terms estar ligado, senão o termo é criado e fica solto, sem conexão com o post.

Como ler os termos salvos pelo Taxonomy Field no tema

Defina o Return Value do campo como Term Object para receber objetos WP_Term ou como Term ID para receber apenas os IDs, e use get_field para ler. Se Save Terms estiver ligado, você também pode ler pelas funções padrão de taxonomia do WordPress.

Grave

Como corrigir o Repeater Field que não salva dados no ACF PRO

O Repeater que não salva no ACF PRO quase sempre perde as últimas linhas porque o PHP descarta variáveis quando o número de campos enviados passa de max_input_vars (padrão 1000). Cada linha do Repeater vira vários campos no POST, então um Repeater grande estoura o limite e grava só parte das linhas, sem erro na tela.

Grave

Como corrigir a incompatibilidade entre JetThemeCore e Astra

A incompatibilidade entre JetThemeCore e Astra aparece quando o Theme Builder do Crocoblock não consegue substituir o cabeçalho, o rodape ou o body do Astra, e a página sai com o layout nativo do tema em vez do template criado. O Override theme header, body e footer parece não ter efeito e o template publicado e ignorado no front-end.

Grave

Como corrigir Dynamic Tags do Elementor que não exibem dados do ACF

As Dynamic Tags do Elementor deixam de exibir dados do ACF quando o campo sai vazio no widget dinamico do editor. As causas reais são o Elementor Pro inativo (Dynamic Tags e recurso Pro), a regra de local do grupo ACF não casar com o post editado, ou o Image Field retornar Array em vez de Image URL.

Atenção

Como corrigir a navegação do slider que não funciona no Happy Addons

O Happy Addons slider não funciona quando a opção de navegação está definida como None, quando o Swiper do Elementor não inicializa por conflito de JavaScript ou cache, ou quando o slider tem um único slide, fazendo as setas e os dots de navegação sumirem ou não avançarem.

Atenção

Como corrigir custom fields do JetEngine que não exibem em cursos do Tutor LMS no WordPress

O custom field do JetEngine não exibe em cursos do Tutor LMS quando a Meta Box não esta atribuida ao post type courses ou quando o Dynamic Field aponta para um object context diferente do curso, deixando o meta field vazio na página renderizada pelo Tutor.

Atenção

Como corrigir o Gallery Field do ACF PRO quando o lightbox não funciona

O lightbox do Gallery Field do ACF PRO não funciona porque o ACF não inclui lightbox próprio: ele só entrega os dados das imagens, e o efeito de ampliar ao clicar depende de o seu template renderizar o link para a imagem cheia com o atributo que a biblioteca de lightbox do tema ou plugin reconhece.

Setores

Extensões

Integrações

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

O que é ACF Taxonomy Field que não salva termos?

Como identificar

Como prevenir

Causa

Como resolver

Perguntas frequentes

Itens relacionados

Como corrigir o Repeater Field que não salva dados no ACF PRO

Como corrigir a incompatibilidade entre JetThemeCore e Astra

Como corrigir Dynamic Tags do Elementor que não exibem dados do ACF

Como corrigir a navegação do slider que não funciona no Happy Addons

Como corrigir custom fields do JetEngine que não exibem em cursos do Tutor LMS no WordPress

Como corrigir o Gallery Field do ACF PRO quando o lightbox não funciona

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