feat(stack): re-plan changed endpoint ports when a stopped stack starts by jgoux · Pull Request #6950 · supabase/cli

jgoux · 2026-10-01T14:43:20Z

With [experimental] stack enabled, changing a port in config.toml (including removing the fixed ports a legacy supabase init writes) used to make the next supabase start fail with "The saved stack cannot adopt these changes". The only way out was to destroy the stack and lose its data. Now, when a stopped stack starts, it applies endpoint port changes and prints each one, for example api: 54321 → 26199. JSON and stream-json output add an endpoint_changes array to the success payload; each entry names the endpoint, the endpoints keys it moved (keys), and its from/to port.

config.toml is the source of truth. The re-plan runs inside the stack owner's startup, while the owner holds the stack lease and before it binds any endpoints. It saves the requested endpoint intents, releases the changed endpoints' rows in the port registry (for example an old sticky automatic port), and claims the new ports through the owner's normal port acquisition, with the usual conflict and occupancy checks. Concurrent starts attach to the winning owner instead of racing it.
Nothing is rolled back. A requested fixed port that is already taken fails the start with the usual port conflict, naming the config key and noting that the new port is saved and the previous automatic port released, so starting again succeeds once the port is free.
Changing which services share the API port is handled too: when a different sharing service requests a fixed API port, the shared listener's old automatic claim is released.
A start request is the complete composition, so excluded or absent services no longer pin the shared API port, and removing [api] port moves the stack to an automatic port instead of being silently ignored. A stopped service excluded during a re-plan has its endpoints rewritten when it is requested again, so the start reuses it and its data instead of creating a second instance.
Endpoints whose configuration didn't change keep their saved ports. A running stack still has to be stopped first, and so does an idle owner kept alive by stack prepare: its error now suggests stack stop then stack start instead of stack destroy. Artifact-version and PostgreSQL major-version changes are still rejected.
The stack definition sent on first registration and the requested configuration for a re-plan reach the spawned owner through a private (0600), short-lived file the owner deletes after reading, instead of its command line, so secrets don't appear in process listings.

ADR 0017 is amended: saved ports stay stable unless the configuration deliberately changes them on a stopped stack.

…ects a config change Maps each incompatible plan path (endpoint port, db major version) to the config.toml key or SUPABASE_*_PORT env var that set it, shows the saved and requested values, and suggests reverting it or running the stack's exact destroy command with a data-loss warning.

…mplete Always suggest the exact --stack-id destroy command instead of an unquoted --stack <name> that re-resolves against the caller's current workdir, carry structured per-change records (service, path, key, saved, requested) plus the recreate command on the JSON/stream-json error envelope via MachineErrorContext, and collect every incompatible member into one error instead of reporting only the first, deduplicating shared API port lines. Use the production planSupabaseComposition planner in the start handler's integration tests instead of a hand-rolled approximation, and derive the port-setting table and createCreations' env-override calls from one shared definition per port to prevent drift.

…name-the-changed-setting-and-the-fix-when-a-saved-stack

…in the stack error Same-major Postgres version differences and catalog-pinned artifact versions have no config.toml key or env var, so the incompatible-stack error no longer suggests reverting major_version or an editable setting for them: it names the full saved and requested builds, drops the revert sentence when nothing is editable, and explains the fix in plain language. Mixed rejections keep the revert advice for the editable keys only, with singular/plural grammar matching their count. destroyCommandFor now takes only the stack id (it never read the name) and is computed once per rejection, reused for both the error suggestion and the JSON/stream-json envelope's recreate_command. Move planSupabaseComposition's export from the main @supabase/stack/effect entrypoint to @supabase/stack/testing, since the CLI only needs it to build a realistic test double for its own composition plan.

github-actions

🤖 AI Review

Both independent reviews were available. Verified all five findings against the checked-out code and trusted conventions: one major rollback race, two minor concerns, and two nits. No findings overlapped.

Findings

Severity	Location	Category	Sources	Claim
🟠 MAJOR	`packages/stack/src/StackHost.ts:584`	`concurrency`	codex	Startup rollback can overwrite mutations committed by an attaching client because RPC becomes available before startup can no longer fail.
🟡 MINOR	`packages/stack/src/StackHost.ts:584`	`error-handling`	codex	Restoration failures are silently discarded, so failed startup can leave changed endpoint intents or claims persisted without reporting that rollback failed.
🟡 MINOR	`packages/stack/src/StackHost.ts:511`	`correctness`	claude	An endpoint intent change can produce a port-change report whose from and to numbers are identical, including text such as api: 26199 → 26199 and a matching endpoint_changes entry.
⚪ NIT	`apps/cli/src/commands/experimental/stack/start/start.handler.ts:505`	`code-quality`	claude	A stopped existing stack that reaches the normal start path resolves requested creations twice, repeating Functions dotenv reads when Functions is enabled.
⚪ NIT	`packages/stack/src/composition/EndpointReplan.integration.test.ts:54`	`comments`	codex	The new test comment contains implementation audit-trail language and exceeds the trusted repository convention for concise fixture explanations.

Stats

Claude findings: 2 · Codex findings: 3 · Confirmed: 5 · Refuted: 0 · Uncertain: 0

Models: claude-opus-5-5 + gpt-6.1-sol · Trigger: auto · Workflow run

This review runs once per PR. A maintainer can request another with a /ai-review comment.

…tart A rejected config change that mixed an editable key (e.g. a port) with a non-editable one (a catalog-pinned artifact or Postgres build) suggested reverting the editable key and dropped the non-editable change, but reverting it alone can't unblock start. Use the destroy-only wording whenever any non-editable change is present, and lead the change-list message with a sentence so it reads standalone in text output. Also document the `stack_changes`/`recreate_command` JSON contract and the intentional `--yes` omission, and make several integration-test assertions that lived inside `if (error instanceof StackCommandStartError)` fail loudly instead of passing vacuously for a different error type.

A changed endpoint on an otherwise-compatible instance now re-plans inside the stack package's own owner startup, while the new owner alone holds the stack's lease, instead of rejecting the start. It saves the updated endpoint intent as one document with the old port claim dropped, just before its own normal endpoint binding claims the requested port or a freshly chosen automatic one, reusing every check a live composition bind already applies. Any startup failure or interruption from that save onward restores the saved state and claims as they read before the re-plan. The CLI passes the requested creations into owner startup through a private file and reports each changed endpoint's old and new port in text, JSON, and stream-json output. A changed artifact version or PostgreSQL major version still fails before modifying the stopped composition.

… attach The saved document and its new endpoint claims now commit, and the rollback scope ends, before the owner serves RPC or publishes its holder, so a later startup failure can no longer undo an attached client's own change along with the re-plan. A restore failure now logs and appends recovery guidance to the original error instead of being swallowed, and an automatic re-plan that resolves back to its previous port is no longer reported as a change. The stopped-stack start handler also reuses the creations already resolved for the re-plan instead of reading the Functions dotenv a second time.

catchCause never ran on interruption, so an external interrupt landing after the prepared document saved but before the claim finished skipped the restore entirely, leaving the saved document with new intents and missing or partial claims. The commit now runs interruptibly under an uninterruptible mask whose restore attempt always runs on any unsuccessful exit, including interruption, and still only extends a genuine typed failure's message with recovery guidance when the restore itself also fails. Updates the ADR, package README, and start command's side-effects doc to describe the rollback as covering only the save-and-claim commit, which finishes before the owner serves RPC or publishes its holder; a later startup failure keeps the committed state and the next start reuses it.

# Conflicts: # apps/cli/src/commands/experimental/stack/start/SIDE_EFFECTS.md # apps/cli/src/commands/experimental/stack/start/start.handler.ts # apps/cli/src/commands/experimental/stack/start/start.integration.test.ts

…port

# Conflicts: # packages/stack/src/effect.ts

…hanges-when-a-stopped-stack-starts

…handling private

Coly010

Really nice to see the destroy-to-change-a-port trap go away. I ran it locally on a Docker stack next to develop, and the headline case, removing [api] port and changing the db port all behave as described.

Requesting changes mainly for the first point, the others are smaller and I'm happy to hear it if you'd rather split any of them out:

the develop merge (3a70647) dropped the annotateCurrentSpan calls #6935 added to start.handler.ts. Nothing tests them, so CI wouldn't catch it
an owner that's already alive (e.g. after stack prepare) skips the re-plan, and the error points at stack destroy
re-adding an excluded service after a re-plan creates a second instance and orphans the old one
a start that fails after the re-plan never reports the move on the retry
small JSON nit on the endpoint_changes label

otherwise, looks good to me!

# Conflicts: # packages/stack/src/composition/Supabase.native.integration.test.ts # packages/stack/src/effect.integration.test.ts

…rt conflicts Restore the start span annotations lost in a develop merge, rewrite a stopped excluded instance's endpoints so a later start reuses it, carry the port conflict from owner startup so the error names the config key, advise stop and start when a live owner meets changed ports, and list the endpoints keys each JSON endpoint change moved.

Coly010

Thanks for turning these around so quickly! I re-ran all three repros on 8380bd8 and they're fixed now. The excluded storage instance gets reused rather than duplicated, and the conflict error reads much better.

Approving so you're unblocked. Two small follow-ups inline on the stop/start advice, and I'd like the first one in before merge if you can

# Conflicts: # packages/stack/src/HostProcess.ts # packages/stack/src/effect.ts # packages/stack/src/internal/host-process.ts

…lans The composition planner marks incompatible entries whose only difference is the intents of endpoints both sides declare, and both the owner's re-plan and the live-owner start advice use that flag. An added or removed endpoint or a version change now gets the destroy advice, and the JSON error envelope omits recreate_command when stop and start is the remedy.

# Conflicts: # packages/stack/src/HostProcess.integration.test.ts

# Conflicts: # apps/cli/src/commands/experimental/stack/start/SIDE_EFFECTS.md

jgoux added 5 commits October 1, 2026 10:17

Merge remote-tracking branch 'origin/develop' into juliengoux/cli-2588-…

72f31d9

…name-the-changed-setting-and-the-fix-when-a-saved-stack

docs(cli): state what the shared port settings guarantee

0247b90

jgoux requested a review from a team as a code owner October 1, 2026 14:43

jgoux self-assigned this Oct 1, 2026

github-actions Bot reviewed Oct 1, 2026

View reviewed changes

depthfirst-app Bot reviewed Oct 1, 2026

View reviewed changes

Comment thread packages/stack/src/HostProcess.ts Outdated

jgoux added 4 commits October 2, 2026 19:45

jgoux force-pushed the juliengoux/cli-2587-apply-configtoml-port-changes-when-a-stopped-stack-starts branch from 525601f to d5fc82b Compare October 2, 2026 17:54

Base automatically changed from juliengoux/cli-2588-name-the-changed-setting-and-the-fix-when-a-saved-stack to develop October 2, 2026 18:33

jgoux added 6 commits October 2, 2026 21:17

Merge remote-tracking branch 'origin/develop' into HEAD

1ba6e2e

# Conflicts: # apps/cli/src/commands/experimental/stack/start/SIDE_EFFECTS.md # apps/cli/src/commands/experimental/stack/start/start.handler.ts # apps/cli/src/commands/experimental/stack/start/start.integration.test.ts

test(stack): accept the Linux bind failure for a conflicting re-plan …

eccfb82

…port

Merge branch 'develop' of github.com:supabase/cli into HEAD

408f6d0

# Conflicts: # packages/stack/src/effect.ts

Merge origin/develop into juliengoux/cli-2587-apply-configtoml-port-c…

7a77dd5

…hanges-when-a-stopped-stack-starts

Merge remote-tracking branch 'origin/develop' into resolve/6950

3a70647

fix(stack): re-plan the shared API listener and keep startup payload …

788ef58

…handling private

Coly010 requested changes Oct 8, 2026

View reviewed changes

jgoux added 2 commits October 8, 2026 14:25

Merge remote-tracking branch 'origin/develop' into resolve/6950

c46790a

# Conflicts: # packages/stack/src/composition/Supabase.native.integration.test.ts # packages/stack/src/effect.integration.test.ts

Coly010 approved these changes Oct 8, 2026

View reviewed changes

Comment thread apps/cli/src/commands/experimental/stack/start/start.handler.ts Outdated

Comment thread apps/cli/src/commands/experimental/stack/start/start.handler.ts Outdated

jgoux added 4 commits October 9, 2026 15:46

Merge remote-tracking branch 'origin/develop' into HEAD

2dbdaf3

# Conflicts: # packages/stack/src/HostProcess.ts # packages/stack/src/effect.ts # packages/stack/src/internal/host-process.ts

Merge remote-tracking branch 'origin/develop' into HEAD

d054f8c

# Conflicts: # packages/stack/src/HostProcess.integration.test.ts

Merge remote-tracking branch 'origin/develop' into HEAD

514e971

# Conflicts: # apps/cli/src/commands/experimental/stack/start/SIDE_EFFECTS.md

Navigation Menu

Repository navigation

feat(stack): re-plan changed endpoint ports when a stopped stack starts - #6950

feat(stack): re-plan changed endpoint ports when a stopped stack starts#6950
jgoux wants to merge 21 commits into
developfrom
juliengoux/cli-2587-apply-configtoml-port-changes-when-a-stopped-stack-starts

jgoux commented Oct 1, 2026 •

edited

Loading

Uh oh!

github-actions Bot left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Coly010 left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Coly010 left a comment

Uh oh!

Uh oh!

Uh oh!

This branch has not been deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

jgoux commented Oct 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot left a comment

Choose a reason for hiding this comment

🤖 AI Review

Findings

Stats

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Coly010 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Coly010 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

This branch has not been deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

jgoux commented Oct 1, 2026 •

edited

Loading