ACF Gallery Field não carrega imagem: como corrigir

Tipo Page Builders

Nome do erro Galeria do ACF PRO não exibe imagens EN: ACF Gallery Field images not displaying

Severidade Atenção

Descrição O ACF Gallery Field não carrega imagem quando o código do template trata o retorno da galeria de forma diferente do Return Format configurado no campo, ou quando o grupo de campos não casa com o post editado, fazendo a galeria voltar vazia no frontend.

O que é Gallery Field do ACF PRO que não carrega imagem?

O ACF Gallery Field é um campo PRO que armazena uma coleção ordenada de imagens da biblioteca de mídia e a devolve ao template conforme o Return Format escolhido no grupo de campos. Segundo a documentação oficial do ACF, o campo oferece três formatos de retorno: Array (cada imagem vira um array associativo com chaves como url, alt, caption e sizes), URL (string) ou ID (inteiro). O problema de imagens que não carregam aparece quando o que o tema espera receber não bate com o que o campo realmente devolve.

O sintoma é direto: get_field na galeria retorna dados, mas nada aparece na página, ou a galeria volta totalmente vazia. A causa raiz mais comum é a divergência entre o Return Format e o código de exibição: usar wp_get_attachment_image esperando um ID enquanto o campo devolve arrays, ou tentar acessar a chave url de um item que na verdade é só o ID inteiro. Soma-se a isso o grupo de campos com regra de localização errada, que faz a galeria sequer ser preenchida no post correto.

Como identificar

A galeria aparece preenchida no editor do post, mas nenhuma imagem é exibida no frontend ao carregar a página.
Um var_dump em get_field(‘galeria’) mostra apenas números inteiros (IDs) quando o template tenta ler chaves como $image[‘url’].
A página exibe a mensagem ‘Notice: Trying to access array offset on value of type int’ ou ‘Undefined array key url’ no lugar das imagens.
A galeria volta vazia (get_field retorna false ou array vazio) mesmo com imagens visivelmente salvas no campo dentro do editor.
As imagens carregam em tamanho errado, esticadas ou como ícone quebrado, porque o sub-size solicitado não existe para aquele anexo.

Antes de começar: Antes de editar arquivos do tema ou rodar a regeneração de thumbnails em produção, faça um backup do site (arquivos e banco de dados) ou aplique a correção primeiro em um ambiente de staging, para poder reverter caso o template quebre.

Como prevenir

Defina e documente o Return Format de cada Gallery Field e escreva o template para esse formato exato, evitando misturar acesso por array e por ID.
Use sempre o Field Name (não o label) em get_field e mantenha um padrão de nomenclatura consistente para os campos do projeto.
Peça tamanhos de imagem que existam no site (registrados via add_image_size) e regenere os thumbnails após cadastrar um tamanho novo.
Valide a regra de localização do grupo de campos em staging antes de publicar, garantindo que a galeria seja preenchida no tipo de post correto.

Causa

O Return Format do campo está configurado como ID (inteiro), mas o template acessa o item como array (por exemplo $image['url']), então o WordPress lê um offset que não existe e a imagem não renderiza.
O Return Format está como Array, mas o template passa o item inteiro para wp_get_attachment_image em vez de passar $image['ID'], fazendo a função receber um array onde espera um ID e devolver string vazia.
A regra de Localização do grupo de campos não casa com o tipo de post sendo exibido, então a galeria nunca é preenchida para aquele post e get_field retorna vazio no frontend.
O tamanho de imagem pedido no template (por exemplo 'medium_large' ou um custom size) não foi gerado para os anexos da galeria, então wp_get_attachment_image cai num arquivo inexistente e exibe ícone quebrado.
O nome do field name usado em get_field está digitado diferente do field name real do campo no grupo (maiúsculas, hífen ou underscore trocados), então o ACF não encontra o campo e devolve null.

Como resolver

Confirme o Return Format do Gallery Field: Em ACF, abra o grupo de campos, edite o Gallery Field e veja o valor de Return Format. Esse valor define se o template recebe um array por imagem, uma URL ou um ID inteiro. Anote o formato, pois o código de exibição precisa casar exatamente com ele.
```
Painel WP -> ACF -> Grupos de Campos -> abra o grupo
Edite o Gallery Field e leia o campo Return Format (Array, URL ou ID)
```
Inspecione o que get_field realmente devolve: No template, faça um dump temporário do valor da galeria para ver a estrutura real antes de iterar. Se vier um array de arrays com chaves url e sizes, o formato é Array; se vier uma lista de números, o formato é ID. Isso elimina o achismo sobre como exibir.
```
No template, recupere a galeria com get_field e atribua a uma variavel
Imprima a variavel com var_dump para inspecionar a estrutura e remova o dump após o diagnostico
```
Ajuste o template ao formato correto: Se o Return Format for ID, percorra os IDs com wp_get_attachment_image passando cada $image_id. Se for Array, leia $image['url'] ou $image['sizes']['medium'] de cada item. Use o padrão de exibição que a doc oficial do ACF documenta para galerias.
```
Formato ID: percorra os IDs com foreach e chame wp_get_attachment_image em cada ID, passando o tamanho desejado
Formato Array: percorra os itens com foreach e leia as chaves url ou sizes de cada imagem para montar a tag de imagem com escape
```
Confira o field name e a regra de localização: Garanta que o nome usado em get_field é idêntico ao Field Name do campo (não ao label) e que a regra de localização do grupo casa com o tipo de post exibido. Um field name digitado errado ou uma regra que não bate fazem a galeria voltar vazia.
```
Painel WP -> ACF -> Grupos de Campos -> abra o Gallery Field e copie o Field Name exato
Ajuste a regra de Localizacao para 'Tipo de Post e igual a' o post exibido
```
Regenere os tamanhos de imagem ausentes: Se as imagens aparecem quebradas só em um tamanho específico, os sub-sizes podem não ter sido gerados para anexos antigos. Peça um tamanho que exista (como 'full') para confirmar e regenere os thumbnails da biblioteca para recriar os sub-sizes.
```
Teste com wp_get_attachment_image( $image_id, 'full' ) para confirmar que o anexo existe
Regenere os thumbnails da biblioteca de mídia (plugin Regenerate Thumbnails ou wp media regenerate via WP-CLI)
```

PHP

<?php
// Exibe um ACF Gallery Field cobrindo os dois Return Formats (Array e ID).
$images = get_field( 'galeria' );

if ( $images ) : ?>
    <ul class="acf-gallery">
        <?php foreach ( $images as $image ) : ?>
            <li>
                <?php
                if ( is_array( $image ) ) {
                    // Return Format = Array.
                    printf(
                        '<img src="%s" alt="%s" loading="lazy">',
                        esc_url( $image['sizes']['large'] ?? $image['url'] ),
                        esc_attr( $image['alt'] )
                    );
                } else {
                    // Return Format = ID.
                    echo wp_get_attachment_image( (int) $image, 'large' );
                }
                ?>
            </li>
        <?php endforeach; ?>
    </ul>
<?php endif;

Perguntas frequentes

Por que o ACF Gallery Field não carrega imagem no frontend

Quase sempre é divergência entre o Return Format do campo e o código do template. Se o formato é ID, o template precisa usar wp_get_attachment_image com cada ID; se é Array, precisa ler a chave url de cada item. Confira o Return Format em ACF e ajuste a exibição.

Como saber qual Return Format meu Gallery Field está usando

Abra o grupo em ACF, edite o Gallery Field e veja o campo Return Format. Para confirmar na prática, faça um var_dump em get_field na galeria: array de arrays com chave url indica formato Array, lista de números indica formato ID.

Qual a diferença entre o formato Array e o formato ID na galeria do ACF

No formato Array cada imagem volta como array associativo com url, alt, caption e sizes, pronto para montar a tag img. No formato ID volta apenas o número do anexo, que você passa para wp_get_attachment_image gerar o HTML da imagem.

Como exibir as imagens de um Gallery Field no template

Recupere o campo com get_field e percorra os itens. No formato ID, chame wp_get_attachment_image em cada ID com o tamanho desejado. No formato Array, leia $image['url'] ou $image['sizes']['medium'] de cada item, como mostra a documentação do ACF.

Por que a galeria do ACF volta vazia mesmo com imagens salvas

Geralmente o field name em get_field está diferente do Field Name real do campo, ou a regra de localização do grupo não casa com o post exibido. Copie o Field Name exato do campo e confirme que a localização aponta para o tipo de post correto.

As imagens aparecem quebradas só em um tamanho, o que houve

O sub-size pedido no template provavelmente não foi gerado para aqueles anexos. Teste com o tamanho full para confirmar que o arquivo existe e regenere os thumbnails da biblioteca para recriar os tamanhos ausentes.

Preciso de JavaScript para mostrar a galeria do ACF

Não para exibir as imagens. A renderização é feita em PHP no template a partir do retorno de get_field. JavaScript só entra se você quiser um carrossel ou lightbox por cima do HTML já gerado pelo servidor.

Informativo

Como corrigir o erro do Advanced Heading no Happy Addons no WordPress

O Advanced Heading do Happy Addons não funciona quando o módulo Pro está inativo, o widget foi desligado nas configurações ou o Elementor não está ativo, fazendo o widget sumir do painel ou exibir o título sem o efeito esperado.

Atenção

Como corrigir o widget Post Grid que não exibe posts no Essential Addons

O widget Post Grid do Essential Addons mostra a grade vazia quando a Query do widget aponta para uma fonte sem conteúdo: um Source de termo sem posts publicados, um Custom Post Type não suportado, um filtro de categoria que não casa ou um Offset maior que o total de posts.

Atenção

Como corrigir o Calendar do JetEngine que não exibe eventos dinâmicos no WordPress

O JetEngine Calendar não exibe eventos dinâmicos quando o campo de data escolhido em Group calendar cells by está vazio ou em formato que o widget não interpreta, quando a query do Listing não retorna posts, ou quando o Listing Template aponta para uma fonte diferente da consultada.

Atenção

Como corrigir o JetPopup que não abre no mobile no WordPress

O JetPopup que não abre no mobile geralmente acontece quando o gatilho do popup depende de um evento que não existe no toque, quando a opção de visibilidade esconde o popup em telas pequenas, ou quando um plugin de cache adia o JavaScript do JetPopup no celular.

Grave

Como corrigir o erro ‘Template Not Found’ no Elementor

O erro "Template Not Found" do Elementor surge quando o site tenta carregar um template salvo que não existe mais no banco ou que veio de outro domínio. É comum após migração ou clonagem sem rodar o Replace URL, ou quando o template referenciado foi excluído da biblioteca.

Grave

Como corrigir erros de compatibilidade entre o Elementor e o PHP 8.3

O erro de compatibilidade do Elementor com o PHP 8.3 acontece quando uma versão antiga do plugin roda num servidor já no PHP 8.3, disparando avisos de deprecated ou um fatal error que derruba o editor ou o front-end. A correção é alinhar o Elementor e o Elementor Pro na última versão e garantir os recursos de PHP exigidos.

Setores

Extensões

Integrações

Como corrigir o Gallery Field com imagens que não carregam no ACF PRO

O que é Gallery Field do ACF PRO que não carrega imagem?

Como identificar

Como prevenir

Causa

Como resolver

Perguntas frequentes

Itens relacionados

Como corrigir o erro do Advanced Heading no Happy Addons no WordPress

Como corrigir o widget Post Grid que não exibe posts no Essential Addons

Como corrigir o Calendar do JetEngine que não exibe eventos dinâmicos no WordPress

Como corrigir o JetPopup que não abre no mobile no WordPress

Como corrigir o erro ‘Template Not Found’ no Elementor

Como corrigir erros de compatibilidade entre o Elementor e o PHP 8.3

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