next/image is failing with Docker Compose

[apudiu]

Summary

In Short:
I've api & web services in the docker-compose.yaml file. Currently everything works perfectly except Next Image(next/image) failing on a client component.
As the component is a client component it should fetch the image. Following is the error in cli (so it runs in server).

TypeError: fetch failed
web  |     at node:internal/deps/undici/undici:13178:13
web  |     at process.processTicksAndRejections (node:internal/process/task_queues:95:5)
web  |     at async fetchExternalImage (/usr/src/app/node_modules/.pnpm/next@14.2.5_react-dom@18.3.1_react@18.3.1__react@18.3.1_sass@1.77.8/node_modules/next/dist/server/image-optimizer.js:580:17)
web  |     at async DevServer.imageOptimizer (/usr/src/app/node_modules/.pnpm/next@14.2.5_react-dom@18.3.1_react@18.3.1__react@18.3.1_sass@1.77.8/node_modules/next/dist/server/next-server.js:650:48)
web  |     at async cacheEntry.imageResponseCache.get.incrementalCache (/usr/src/app/node_modules/.pnpm/next@14.2.5_react-dom@18.3.1_react@18.3.1__react@18.3.1_sass@1.77.8/node_modules/next/dist/server/next-server.js:182:65)
web  |     at async /usr/src/app/node_modules/.pnpm/next@14.2.5_react-dom@18.3.1_react@18.3.1__react@18.3.1_sass@1.77.8/node_modules/next/dist/server/response-cache/index.js:90:36
web  |     at async /usr/src/app/node_modules/.pnpm/next@14.2.5_react-dom@18.3.1_react@18.3.1__react@18.3.1_sass@1.77.8/node_modules/next/dist/lib/batcher.js:45:32 {
web  |   [cause]: AggregateError [ECONNREFUSED]:
web  |       at internalConnectMultiple (node:net:1118:18)
web  |       at afterConnectMultiple (node:net:1685:7)
web  |       at TCPConnectWrap.callbackTrampoline (node:internal/async_hooks:130:17) {
web  |     code: 'ECONNREFUSED',
web  |     [errors]: [ [Error], [Error] ]
web  |   }
web  | }
web  |  GET /_next/image?url=http%3A%2F%2Flocalhost%3A3000%2Fuploads%2Fsample%2F9.png&w=1200&q=75 500 in 41ms
web  |  GET /_next/image?url=http%3A%2F%2Flocalhost%3A3000%2Fuploads%2Fsample%2F9.png&w=1200&q=75 500 in 29ms

Note: The images this failed to fetch are available with the API URL (http://localhost:3000/uploads/sample/9.png) from host.
Following is the component

'use client'
import Image from "next/image";

type PostImgProps = {
  imgUrl: string;
};

const PostImg = (p: PostImgProps) => {
  // if I comment out the "Image" below there's no error remains
  return (
    <Image
      className="object-cover"
      src={p.imgUrl}
      alt="post image"
      width={1200}
      height={1000}
    />
  );
};

export default PostImg;

I know that Next.js tries to render client components in the server too. So I've imported it like

const PostImg = dynamic(
  () => import('@/path/to/postImg'),
  {
    ssr: false, // completely disable server side rendering
    loading: () => (
      <div className="...">
        <!-- loader code -->
      </div>
    )
  }
);

to disable server rendering. But I am still facing the error. As far as I can tell. As the component is still being rendered on the server. It fails to pull the image because the URL (p.imgUrl in PostImg component) is unavailable on the server. btw, it's http://localhost:3xxx/path/to/img.ext. In the server instead of localhost we need docker service name there which is api in my case. but how do I configure that?

Thank you in advance for the help :)

Additional information

Node: 20
Next: 14.2.5

Example

No response

[apudiu]

I've also created a question on StackOverflow

[icyJoseph]

The issue is that, next/image works a bit differently than you might think.

The image src, points to a /_next/image, endpoint, with a url query parameter. Then the next server, uses that information to retrieve the image, server side, then resize/optimize the image, and finally, answer back to the client with the image.

So the whole dynamic thing, of disable server side rendering has no effect, for your issue.

I guess you could do:

http://api/path/to/img.ext

And since that's all happening server side, you'd be fine. You probably also need to add these to the next.config.js file, either as remote patterns or domains, though the former is preferred.

[apudiu]

Thanks @icyJoseph, That feature of next/image is making the issue in the environment my app runs. API & the UI are in docker container (& under the same network). Next.js is allowed to call API using http:// only from the browser (outside of the container). When server-side that thing only can call API using service name (like api) & next image is failing here. Next.js has no solution for this except disabling image optimization, which is not a solution though.

[ThukuWakogi]

Did you get a solution for this?

[apudiu]

No, just disabled image optimization in development as I'm using Docker only for development

[CoderDeltaLAN]

Context

• Next.js 14.2.x in Docker Compose (web + api)
• next/image fails with ECONNREFUSED when the src points to http://localhost:3000/...

Why
next/image optimization happens server-side. Inside the web container, localhost is the web container itself, not your api. So the optimizer tries to fetch http://localhost:3000/... from the wrong place and gets ECONNREFUSED.

Fix (minimum viable)

1. Use the Compose service name (DNS on the bridge network) in the image URL:

   // good: hits the api container from inside web
   <Image src="http://api:3000/uploads/sample.png" width={1200} height={675} alt="..." />
   // bad: localhost points to the web container, not api
   // <Image src="http://localhost:3000/uploads/sample.png" ... />

2. Allow that host in next.config.js with remotePatterns including port:

   /** @type {import('next').NextConfig} */
   const nextConfig = {
     images: {
       remotePatterns: [
         { protocol: 'http', hostname: 'api', port: '3000', pathname: '/uploads/**' },
       ],
     },
   };
   module.exports = nextConfig;

3. Compose example (names matter):

   services:
     api:
       image: node:20
       # expose your API on 3000
     web:
       image: node:20
       depends_on: [api]
       # both on the default bridge network so "api" is resolvable

4. If you need a single source for both server and browser:

   • Server (optimizer) can use http://api:3000.
   • Browser must use a public host. Provide both via env:

     const serverBase = process.env.INTERNAL_API_URL ?? 'http://api:3000';
     const publicBase = process.env.NEXT_PUBLIC_API_URL ?? 'http://localhost:3000';

     And build the src accordingly on server/client.

5. Quick diagnostic

   • From the web container: curl -I http://api:3000/uploads/sample.png should be 200.
   • If you’re behind a proxy (nginx/traefik), forward X-Forwarded-Host/Proto.

6. Temporary bypass to confirm root cause:

   // next.config.js
   module.exports = { images: { unoptimized: true } }

   If this works, the issue was the internal URL/host allowlist, not your component.

Notes

• Remote images config: https://nextjs.org/docs/app/api-reference/components/image#remote-images
• remotePatterns fields (protocol | hostname | port | pathname) are supported.

If this solves it, please Mark as answer so others can find it.

[prafuldivani]

The issue occurs because next.config.ts (or next.config.js) is not being copied into the final Docker image. Make sure the config file is included in the runtime stage.

Add one of the following lines to your Dockerfile:
COPY --from=builder /app/next.config.ts ./
or, if you’re using JavaScript:
COPY --from=builder /app/next.config.js ./

Once the config file is present in the final image, the issue is resolved.

[apudiu]

did you tried this?

[prafuldivani]

Yes, of course.

[tomihq]

didn't work for me

[KeepALifeUS]

This is a Docker networking issue. Inside your web container, localhost:3000 refers to the container itself, not your api service.

Solution

1. Use Docker service names for internal URLs

In your Docker Compose, services communicate via their service names, not localhost. So http://api:3000 instead of http://localhost:3000.

2. Configure next.config.js for Docker

// next.config.js
module.exports = {
  images: {
    remotePatterns: [
      {
        protocol: 'http',
        hostname: 'api',  // Docker service name
        port: '3000',
        pathname: '/uploads/**',
      },
      {
        protocol: 'http',
        hostname: 'localhost',  // For local development
        port: '3000',
        pathname: '/uploads/**',
      },
    ],
  },
}

3. Use environment variables for the image URL

// In your component or API
const API_URL = process.env.NEXT_PUBLIC_API_URL || 'http://localhost:3000';

// Pass this URL to your component
<PostImg imgUrl={`${API_URL}/uploads/sample/9.png`} />

4. Docker Compose setup

# docker-compose.yml
services:
  api:
    # ...your api config
    networks:
      - app-network

  web:
    # ...your web config
    environment:
      - INTERNAL_API_URL=http://api:3000  # For server-side
      - NEXT_PUBLIC_API_URL=http://localhost:3000  # For client-side
    networks:
      - app-network
    depends_on:
      - api

networks:
  app-network:
    driver: bridge

5. Handle both environments in your code

// utils/getImageUrl.ts
export function getImageUrl(path: string): string {
  // Server-side: use Docker service name
  if (typeof window === 'undefined') {
    return `${process.env.INTERNAL_API_URL}${path}`;
  }
  // Client-side: use public URL
  return `${process.env.NEXT_PUBLIC_API_URL}${path}`;
}

Key Point

The Next.js image optimizer runs server-side, even for client components. So it needs to reach your API using the Docker internal network (http://api:3000), not localhost.