Repository navigation
fix(cli)!: give functions serve failures typed errors - #7506
Merged
Merged
Conversation
`functions serve` reported its config, env-file, signing-key, env-staging and Docker bring-up failures as a plain `Error`, so they all shared one unclassified fingerprint. Each site now fails with a typed error that carries a closed `reason` set where the error is built: - ServeConfigError, ServeEnvFileError, ServeFilesystemError - EdgeRuntimeDockerStepError (create/cp/start) and DockerResourceCreateError (network/volume), classified from Docker's stderr at construction Messages and exit codes are unchanged. A daemon-unreachable failure during those Docker steps now shows a start-Docker suggestion. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
A missing explicit --env-file now reports reason not_found; other read failures keep their filesystem cause and parse failures report syntax. Legacy start and functions serve report ServeEnvFileError instead of a plain error. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…ehaviour Docker step cases state their expected fingerprint and suggestion in the table, with daemon_down and start rows added. Inspect flag, multiline env name and directory env-file cases assert the typed error code. The serve telemetry note no longer claims per-step fingerprints for filesystem failures, and deploy documents the Docker network and volume error code. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Signing-key, jwt_secret and deno_version failures are rejected by shared config validation before serve's own checks run, so the typed variants were unreachable. Serve keeps its plain errors for them, with messages unchanged. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
🤖 AI Review
Verified all three Claude findings: two minor documentation/remediation concerns and one error-naming nit. The Docker-hint finding is narrowed to socket-permission failures; missing executables fail earlier. Codex's independent review completed with no findings. Verification was by code inspection; tests were not run.
Findings
| Severity | Location | Category | Sources | Claim |
|---|---|---|---|---|
| 🟡 MINOR | apps/cli/src/commands/start/start.integration.test.ts:5715 |
documentation |
claude | The PR changes JSON error codes and Docker remediation hints for supabase start without updating that command's SIDE_EFFECTS.md. |
| 🟡 MINOR | apps/cli/src/shared/functions/serve.errors.ts:257 |
error-messages |
claude | Docker socket-permission failures receive the new 'Start Docker' suggestion even when Docker is already running; starting Docker does not resolve the access problem. |
| ⚪ NIT | apps/cli/src/shared/functions/serve.ts:1748 |
error-classification |
claude | An invalid multiline secret name from config.toml is labeled ServeEnvFileError even though the failing value need not originate in an env file. |
Stats
Claude findings: 3 · Codex findings: 0 · Confirmed: 3 · 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.
… suggestion Document the typed bring-up errors in start's SIDE_EFFECTS.md, say that ServeEnvFileError also covers configured secrets, and make the start-Docker suggestion cover an inaccessible Docker socket. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
The error also covers invalid names from configured secrets, so a source-neutral name fits. The class is unreleased, so no fingerprint changes. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
jgoux
approved these changes
Nov 5, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
TL;DR
functions servereported its config, env-file, env-staging and Docker bring-up failures as a plainError, so all of them shared one unclassified error. They now use typed errors with a reason set where the error is built; Docker reasons are read from Docker's output at that point.What changed
ServeConfigError: invalid--inspectflags or a missing local import.ServeEnvError: the env file is missing, can't be read or doesn't parse, or an env file or configured secret has an invalid variable name.ServeFilesystemError: staging the env files fails.EdgeRuntimeDockerStepError:docker create,cporstartfor the Edge Runtime container fails. The reason is one of: daemon not running, port in use, container name conflict, mount denied, disk full, or other. "Other" is classified as a runtime crash and fingerprinted by step.DockerResourceCreateError: Docker network or volume creation fails. The reason is one of: daemon not running, address pool exhausted, or other.disk_fullandengine_command_copy.edge_runtime.docker_stepandedge_runtime.failure_reason.Behaviour change
Breaking for scripts that read the JSON error envelope: with
--output json,error.codefor these failures is now the new error name instead ofUnknownError. This applies to:functions servesupabase start: a malformedsupabase/functions/.env, the missing-import check, and the Edge Runtime containerfunctions deploy: Docker network and volume creationEnv-file failures in
startandfunctions servekept the plain error in #7499; they now reportServeEnvError. The stack backend is unchanged.When Docker isn't running during the container steps, a start-Docker suggestion replaces the generic
--debughint. Messages and exit codes are unchanged.Linked issue
None
🤖 Generated with Claude Code