Astro Remote Image Is Not Allowed: Fix domains and remotePatterns

Match the URL, not the provider name#

The hostname is only the host, without https://, a path, or a trailing slash. If the page uses https://cdn.example.com, a rule for images.example.com does not match. If the origin uses a non-default port, include that port in the pattern as well.

Use pathname to constrain the folders Astro may fetch. A rule for /cdn/** should not be treated as permission to fetch every path on the host. Keep separate patterns for separate trusted origins, and avoid a broad wildcard when a deployment uses one known image bucket or CDN path.

The Astro remote-image error reference describes the two allowlist options. The asset API reference documents the fields used by remotePatterns, including the protocol, hostname, port, and pathname match.

Choose domains or remotePatterns#

Use domains when the whole hostname is trusted and path-level matching would not add useful protection:

1
export default defineConfig({
2
  image: {
3
    domains: ['images.example.com'],
4
  },
5
});

Prefer remotePatterns when the same host serves unrelated content, when you need to require HTTPS, or when only a CDN folder should be available to the image pipeline. It makes the boundary visible in code review and reduces accidental fetches from another path or subdomain.

Do not put a full URL in domains and expect it to work. Do not use an application route that redirects to an image host and assume Astro will treat the final host as the original match. Configure the host that Astro actually requests, then verify redirects and authorization separately.

Check remote images in components#

The allowlist applies when using Astro’s optimized image APIs, including Image and Picture. A remote image component can then use a URL from frontmatter or another data source:

1
---
2
import { Image } from 'astro:assets';
3

4
const imageUrl = 'https://images.example.com/cdn/posts/hero.webp';
5
---
6

7
<Image src={imageUrl} alt="A deployment dashboard" width={1200} height={630} />

If you use inferSize for a remote image, Astro must be able to fetch dimensions from an authorized remote domain. An allowlist entry that is too broad may hide the problem in development, while an entry that is too narrow will fail the build when the actual URL changes. Prefer explicit width and height for content whose source is controlled by an external API.

If you intentionally use a plain <img src="...">, that bypasses Astro’s asset transformation, but it does not provide the same optimization, dimension inference, or validation behavior. Pick the rendering path deliberately instead of changing component types only to silence the error.

Verify the fix before deployment#

Use the exact URL from the failing content, not a simplified example:

1
pnpm astro check
2
pnpm build

If the build still fails, log the URL’s protocol, hostname, port, and pathname from the content source without printing signed query parameters or access tokens. Check for a www/non-www change, an HTTP redirect, a different CDN hostname in production, and a path prefix added by the image provider.

Keep the pattern in the same configuration file that is used by the deployment build. A local astro.config.mjs change cannot fix a separate production build if the deployment points at another package or uses a different generated configuration.

For the container boundary around an Astro site, the Astro static site with Caddy and Docker guide is a useful companion. The image allowlist belongs to Astro’s build/runtime configuration; Caddy only serves the resulting site or proxies the chosen image origin.

FAQ#