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

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.

Erros relacionados

- [Como corrigir Custom Fields que não aparecem no frontend no ACF PRO](https://full.services/wp-fixer/corrigir-custom-fields-frontend-acf-pro/)
- [Como corrigir o Repeater Field que não salva dados no ACF PRO](https://full.services/wp-fixer/corrigir-repeater-nao-salva-acf-pro/)
- [Como corrigir o Relationship Field no ACF PRO](https://full.services/wp-fixer/corrigir-relationship-field-acf-pro/)

## 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

1. 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)
```

2. 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
```

3. 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
```

4. 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
```

5. 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)
```


## Código

```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.

**Fonte:** [Advanced Custom Fields — Gallery Field](https://www.advancedcustomfields.com/resources/gallery/)