Image Field ACF Não Retorna URL: como corrigir

Tipo Page Builders

Nome do erro Image Field do ACF PRO não retorna URL EN: ACF PRO Image Field not returning URL

Severidade Atenção

Descrição O Image Field do ACF PRO não retorna a URL quando o Return Format do campo está como Image Array ou Image ID, mas o template usa o valor como se fosse a string da URL. O ACF devolve um array ou um número de anexo, então o atributo src da imagem sai quebrado ou vazio.

O que é Image Field do ACF que não retorna URL?

O Image Field do ACF PRO tem três opções de Return Format na configuração do campo: Image Array, Image URL e Image ID. Cada opção devolve um tipo de dado diferente quando você lê o campo com get_field. O Image Array devolve um array com chaves como url, alt, width e height. O Image URL devolve só a string da URL. O Image ID devolve o número do anexo na biblioteca de mídia. O erro de não retornar URL acontece quando o template foi escrito esperando a string da URL, mas o campo está configurado como Array ou ID. Como o ACF não dispara erro fatal, o resultado é silencioso: a tag de imagem renderiza com o src vazio, com a palavra Array, ou com um número cru no lugar do caminho do arquivo.

Como identificar

A imagem não aparece no frontend e o atributo src da tag fica vazio ao inspecionar o HTML.
No lugar da imagem o navegador imprime a palavra Array como texto, sinal de que o campo devolveu um array e foi tratado como string.
var_dump do campo imprime um array com as chaves url, alt e sizes em vez de uma string única com o caminho.
O src da imagem mostra um número inteiro como 482 em vez de um caminho de arquivo, sinal de Return Format igual a Image ID.
A mensagem Array to string conversion aparece no log de debug quando o template concatena o campo direto na URL.

Como prevenir

Defina o Return Format do Image Field uma vez por projeto e padronize: Image URL para uso simples no src, Image Array quando precisar de alt e tamanhos.
Escape toda saída de imagem com esc_url no src e esc_attr no alt antes de imprimir, evitando HTML quebrado por valores inesperados.
Valide o retorno com uma checagem de vazio antes de montar a tag, porque a imagem pode ter sido apagada da biblioteca de mídia.
Dentro de Repeater e Flexible Content, sempre leia a imagem com get_sub_field, reservando get_field para campos de nível superior.

Causa

O Return Format do campo está como Image Array, então get_field devolve um array e o template precisa ler a chave url em vez de usar o valor inteiro.
O Return Format do campo está como Image ID, então get_field devolve o número do anexo e o caminho do arquivo precisa ser resolvido com wp_get_attachment_image_url.
O template chama the_field no Image Field, que tenta imprimir o array ou o ID direto e gera a palavra Array ou um número no HTML.
O campo está dentro de um Repeater ou de um Flexible Content e o código lê get_field do campo pai em vez de get_sub_field dentro do laço, recebendo um valor que não é a URL.
A imagem foi apagada da biblioteca de mídia depois de selecionada, então o anexo não existe mais e wp_get_attachment_image_url devolve false para aquele ID.

Como resolver

Descubra qual Return Format o campo devolve: Imprima o valor do campo no template para ver o tipo de dado que o ACF entrega naquele contexto. Se vier um array com a chave url, o campo é Array. Se vier um número, o campo é ID. Se vier uma string com http, o campo já é URL e o problema está em outro lugar.
```
var_dump( get_field('imagem') );
```
Se o campo for Image Array, leia a chave url: Quando o Return Format é Image Array, o caminho do arquivo mora na chave url do array. Acesse essa chave e escape a saída antes de imprimir no atributo src. O array ainda traz alt, width e height para montar a tag completa.
```
$img = get_field('imagem');
echo esc_url( $img['url'] );
```
Se o campo for Image ID, resolva o caminho pelo ID: Quando o Return Format é Image ID, o campo devolve só o número do anexo. Converta esse ID em URL com a função do WordPress, escolhendo o tamanho registrado que você precisa, e escape o resultado.
```
$id  = get_field('imagem');
$url = wp_get_attachment_image_url( $id, 'large' );
echo esc_url( $url );
```
Ou troque o Return Format para Image URL no campo: Se o template só precisa do caminho da imagem, ajuste a configuração do campo para devolver a URL pronta. Depois disso get_field passa a devolver a string direta e the_field imprime o caminho sem array. Caminho no menu: Custom Fields -> Field Groups -> seu grupo -> campo de imagem -> Return Format -> Image URL.
```
Custom Fields -> Field Groups -> [grupo] -> [campo imagem] -> Return Format -> Image URL
```
Dentro de Repeater ou Flexible Content, use get_sub_field: Se a imagem está em uma linha de Repeater ou em um layout de Flexible Content, o valor só é acessível por get_sub_field dentro do laço have_rows. Ler o campo pai por get_field não devolve a URL da linha atual.
```
$img = get_sub_field('imagem');
echo esc_url( $img['url'] );
```

PHP

<?php
// Exibe um Image Field do ACF independente do Return Format configurado.
$imagem = get_field( 'imagem' );

if ( is_array( $imagem ) && ! empty( $imagem['url'] ) ) {
    // Return Format: Image Array.
    printf(
        '<img src="%s" alt="%s">',
        esc_url( $imagem['url'] ),
        esc_attr( $imagem['alt'] )
    );
} elseif ( is_numeric( $imagem ) ) {
    // Return Format: Image ID.
    $url = wp_get_attachment_image_url( (int) $imagem, 'large' );
    if ( $url ) {
        printf( '<img src="%s" alt="">', esc_url( $url ) );
    }
} elseif ( is_string( $imagem ) && $imagem ) {
    // Return Format: Image URL.
    printf( '<img src="%s" alt="">', esc_url( $imagem ) );
}

Perguntas frequentes

Por que o Image Field do ACF imprime a palavra Array em vez da imagem

O Return Format do campo está como Image Array e o template tenta imprimir o array inteiro como se fosse texto. Leia a chave url do array com get_field e escape com esc_url, ou troque o Return Format do campo para Image URL na configuração.

Qual a diferença entre Image Array, Image URL e Image ID no ACF

Image Array devolve um array com url, alt, width e sizes. Image URL devolve só a string da URL, pronta para o src. Image ID devolve o número do anexo, que você converte em caminho com wp_get_attachment_image_url. Escolha conforme o que o template precisa.

Como pego só a URL quando o campo está como Image Array

Guarde o retorno de get_field em uma variável e acesse a chave url do array. Imprima com esc_url para escapar a saída. O mesmo array traz alt e sizes caso você queira montar a tag de imagem completa com texto alternativo.

O campo devolve um número em vez do caminho da imagem, o que é

O Return Format está como Image ID, então o ACF entrega o número do anexo. Passe esse ID para wp_get_attachment_image_url com o tamanho desejado para obter a URL, ou mude o Return Format do campo para Image URL se quiser o caminho direto.

Posso usar the_field para exibir o Image Field

Só funciona bem quando o Return Format é Image URL, porque the_field imprime a string direta. Com Image Array ou Image ID o the_field imprime a palavra Array ou um número. Para esses formatos use get_field, monte a tag e escape a saída.

A imagem some dentro de um Repeater, como corrijo

Dentro de Repeater ou Flexible Content a imagem só sai por get_sub_field, chamado dentro do laço have_rows. Usar get_field no campo pai não devolve a imagem da linha atual. Acesse a chave url do retorno e escape com esc_url antes de imprimir.

Por que a imagem aparecia e parou de aparecer de repente

O anexo selecionado pode ter sido removido da biblioteca de mídia. Com Image ID a função wp_get_attachment_image_url devolve false para um ID inexistente. Confirme se o arquivo ainda existe na mídia e selecione a imagem de novo no campo.

Atenção

Como corrigir o erro de File Upload por permissões de pasta no ACF PRO

O erro de File Upload por permissões de pasta no ACF PRO acontece quando o campo File usa a media popup nativa do WordPress para enviar um arquivo, mas a pasta wp-content/uploads não tem permissão de escrita para o usuário do servidor web, e o upload falha antes de o arquivo ser anexado ao campo.

Atenção

Como corrigir fontes personalizadas que não carregam no Astra Pro

A fonte personalizada do Astra não carrega quando o site exibe a fonte de fallback no lugar da enviada, porque o plugin Custom Fonts está inativo, o peso do arquivo enviado não bate com o peso escolhido na tipografia, ou o cache de página entrega o head antigo sem o @font-face. A correção ativa o módulo, alinha os pesos e limpa o cache.

Atenção

Como corrigir ícones do Font Awesome que não aparecem no Elementor

Ícones do Font Awesome somem no Elementor quando a biblioteca de ícones não é carregada no frontend, quando a classe usada é do Font Awesome 4 sem o suporte ativo, ou quando o CSS de ícones está em cache desatualizado.

Grave

Como corrigir o conflito de templates de curso entre Tutor LMS e Elementor

A página de curso fica sem o layout do Elementor (ou mostra o template padrão do Tutor LMS) porque o addon Tutor LMS do Elementor não esta ativo ou a prioridade de template aponta para o template embutido do plugin em vez do seu template Elementor.

Crítico

Como corrigir erro 500 ao editar com Elementor

O erro 500 ao editar com Elementor é um Internal Server Error que derruba o editor ao abrir ou salvar a página, geralmente com tela branca ou aviso de erro. A causa quase sempre é memória PHP esgotada, um limite de servidor estourado (max_input_vars/tempo) ou um conflito de plugin que dispara um erro fatal no PHP.

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.

Setores

Extensões

Integrações

Como corrigir o Image Field no ACF PRO

O que é Image Field do ACF que não retorna URL?

Como identificar

Como prevenir

Causa

Como resolver

Perguntas frequentes

Itens relacionados

Como corrigir o erro de File Upload por permissões de pasta no ACF PRO

Como corrigir fontes personalizadas que não carregam no Astra Pro

Como corrigir ícones do Font Awesome que não aparecem no Elementor

Como corrigir o conflito de templates de curso entre Tutor LMS e Elementor

Como corrigir erro 500 ao editar com Elementor

Como corrigir a incompatibilidade entre JetThemeCore e Astra

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