Skip to content

armgit / spree

Public Imported from GitHub
0

Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.

Added hints for Docker network exhaustion and busy mail ports (#14989)

Damian Legawiec70ab2cd786ea
diff --git a/.changeset/docker-network-pool-hint.md b/.changeset/docker-network-pool-hint.md
new file mode 100644
index 0000000000..0c60518175
--- /dev/null
+++ b/.changeset/docker-network-pool-hint.md
@@ -0,0 +1,5 @@
+---
+"@spree/cli": patch
+---
+
+When Docker runs out of network addresses, `spree init`, `spree dev` and the other commands that start containers now explain why and how to remove the old networks, instead of showing only the raw Docker error.
diff --git a/.changeset/mailpit-port-hint.md b/.changeset/mailpit-port-hint.md
new file mode 100644
index 0000000000..1162c4f525
--- /dev/null
+++ b/.changeset/mailpit-port-hint.md
@@ -0,0 +1,5 @@
+---
+"create-spree-app": patch
+---
+
+When the mail catcher's usual ports are taken, the installer now says what is usually holding them and how to free them.
diff --git a/packages/cli/src/docker.ts b/packages/cli/src/docker.ts
index 93149597f7..0903b804ad 100644
--- a/packages/cli/src/docker.ts
+++ b/packages/cli/src/docker.ts
@@ -5,10 +5,37 @@ import { backendTaskCommand, PREPARE_DATABASE } from './backend.js'
import { hasMonorepoSpreePath } from './context.js'
export async function dockerCompose(args: string[], projectDir: string, options?: ExecaOptions) {
- return execa('docker', ['compose', ...args], {
- cwd: projectDir,
- ...options,
- })
+ try {
+ return await execa('docker', ['compose', ...args], {
+ cwd: projectDir,
+ ...options,
+ })
+ } catch (error) {
+ throw withDockerHint(error)
+ }
+}
+
+// Docker's default address pools hold about 30 bridge networks, and every
+// compose project keeps its `<name>_default` network after its containers
+// stop — so a machine with many old projects fails to create a new one with
+// a daemon message that names neither the cause nor the fix.
+const ADDRESS_POOLS_EXHAUSTED = /all predefined address pools have been fully subnetted/i
+
+function isAddressPoolExhausted(error: unknown): boolean {
+ return ADDRESS_POOLS_EXHAUSTED.test(error instanceof Error ? error.message : String(error))
+}
+
+function withDockerHint(error: unknown): unknown {
+ if (!isAddressPoolExhausted(error)) return error
+
+ const message = error instanceof Error ? error.message : String(error)
+ return new Error(
+ `${message}\n\nDocker has no free network addresses left, usually because old projects left their networks behind. ` +
+ `List them with ${pc.cyan('docker network ls')} and remove the ones you no longer need with ${pc.cyan('docker network rm <name>')}. ` +
+ `${pc.cyan('docker network prune')} removes every network on this machine that no container is using, ` +
+ 'including networks other tools created and still expect to find.',
+ { cause: error },
+ )
}
// web and worker share one bundle_cache named volume and, in the dev compose,
@@ -27,17 +54,22 @@ export async function dockerCompose(args: string[], projectDir: string, options?
//
// Best-effort: a failed prime (image not built yet, daemon hiccup) is swallowed
// so the caller's real `up` builds/pulls and surfaces the genuine error — we
-// remove a race, we never mask a failure.
+// remove a race, we never mask a failure. The exception is a project network
+// Docker cannot create: this is the first `up`, and `spree dev`'s foreground
+// `up` streams stderr uncaptured, so this is the one place its hint can show.
export async function primeBundleVolume(
projectDir: string,
options?: { stdio?: 'inherit' | 'pipe' | 'ignore' },
): Promise<void> {
+ const stdio = options?.stdio ?? 'inherit'
try {
await dockerCompose(['up', '-d', '--no-deps', 'web'], projectDir, {
- stdio: options?.stdio ?? 'inherit',
+ stdin: stdio,
+ stdout: stdio,
+ stderr: stdio === 'inherit' ? ['pipe', 'inherit'] : 'pipe',
})
- } catch {
- // fall through to the caller's `up`, which reports any real failure
+ } catch (error) {
+ if (isAddressPoolExhausted(error)) throw error
}
}
diff --git a/packages/cli/tests/docker.test.ts b/packages/cli/tests/docker.test.ts
index cdd615cae3..2487c61faf 100644
--- a/packages/cli/tests/docker.test.ts
+++ b/packages/cli/tests/docker.test.ts
@@ -17,10 +17,12 @@ vi.mock('@clack/prompts', () => ({
import { execa } from 'execa'
import {
captureTask,
+ dockerCompose,
dockerComposeCapture,
dockerComposeExecOrRun,
dockerComposeRun,
prepareDatabase,
+ primeBundleVolume,
} from '../src/docker'
const mockExeca = vi.mocked(execa)
@@ -111,6 +113,61 @@ describe('dockerComposeRun', () => {
})
})
+describe('dockerCompose', () => {
+ afterEach(() => mockExeca.mockReset())
+
+ it('explains an exhausted Docker network pool and how to free it', async () => {
+ const daemonError = new Error(
+ 'Command failed with exit code 1: docker compose up -d\nError response from daemon: all predefined address pools have been fully subnetted',
+ )
+ mockExeca.mockRejectedValueOnce(daemonError)
+
+ const error = await dockerCompose(['up', '-d'], '/proj').catch((caught: Error) => caught)
+
+ expect(error).toBeInstanceOf(Error)
+ expect((error as Error).message).toContain('docker network ls')
+ expect((error as Error).cause).toBe(daemonError)
+ })
+
+ it('rethrows any other failure unchanged', async () => {
+ const daemonError = new Error('Command failed with exit code 1: docker compose up -d')
+ mockExeca.mockRejectedValueOnce(daemonError)
+
+ await expect(dockerCompose(['up', '-d'], '/proj')).rejects.toBe(daemonError)
+ })
+})
+
+describe('primeBundleVolume', () => {
+ afterEach(() => mockExeca.mockReset())
+
+ it('captures stderr while still streaming it to the terminal', async () => {
+ await primeBundleVolume('/proj')
+
+ expect(mockExeca).toHaveBeenCalledWith('docker', ['compose', 'up', '-d', '--no-deps', 'web'], {
+ cwd: '/proj',
+ stdin: 'inherit',
+ stdout: 'inherit',
+ stderr: ['pipe', 'inherit'],
+ })
+ })
+
+ it('stops on an exhausted Docker network pool so its hint reaches the operator', async () => {
+ mockExeca.mockRejectedValueOnce(
+ new Error(
+ 'Error response from daemon: all predefined address pools have been fully subnetted',
+ ),
+ )
+
+ await expect(primeBundleVolume('/proj')).rejects.toThrow('docker network ls')
+ })
+
+ it("leaves any other failure to the caller's own `up`", async () => {
+ mockExeca.mockRejectedValueOnce(new Error('pull access denied'))
+
+ await expect(primeBundleVolume('/proj')).resolves.toBeUndefined()
+ })
+})
+
describe('prepareDatabase', () => {
afterEach(() => mockExeca.mockReset())
diff --git a/packages/create-spree-app/src/index.ts b/packages/create-spree-app/src/index.ts
index 17ac9f0d3b..76ecd15a83 100644
--- a/packages/create-spree-app/src/index.ts
+++ b/packages/create-spree-app/src/index.ts
@@ -78,6 +78,11 @@ const program = new Command()
)
}
}
+ if (mailpitSmtpPort !== 1025 || mailpitUiPort !== 8025) {
+ p.log.info(
+ `Another program is using those ports, often an earlier Spree project's mail catcher. ${pc.cyan('docker ps')} lists running containers; ${pc.cyan('docker compose down')} in that project's folder frees the ports.`,
+ )
+ }
await scaffold({ ...options, port, mailpitSmtpPort, mailpitUiPort })