charmbracelet/crush · error · ErrServerShuttingDown

server is shutting down

Error message

server is shutting down

What it means

ErrServerShuttingDown reports that the server has committed to exiting and refuses new work: workspace creates during the shutdown path are rejected by admitLocked, and checkStatus maps HTTP 503 responses to this sentinel. The work is not lost — a replacement server can be started and the request retried against it. Declared in both internal/backend (server side) and internal/client (client-side sentinel for 503).

Source

Thrown at internal/backend/backend.go:40

	"github.com/charmbracelet/crush/internal/proto"
	"github.com/charmbracelet/crush/internal/skills"
	"github.com/charmbracelet/crush/internal/ui/util"
	"github.com/charmbracelet/crush/internal/version"
	"github.com/google/uuid"
)

// Common errors returned by backend operations.
var (
	ErrWorkspaceNotFound       = errors.New("workspace not found")
	ErrLSPClientNotFound       = errors.New("LSP client not found")
	ErrAgentNotInitialized     = errors.New("agent coordinator not initialized")
	ErrPathRequired            = errors.New("path is required")
	ErrInvalidPermissionAction = errors.New("invalid permission action")
	ErrUnknownCommand          = errors.New("unknown command")
	ErrInvalidClientID         = errors.New("invalid client_id")
	ErrClientNotAttached       = errors.New("client not attached")
	ErrWorkspaceClosing        = errors.New("workspace closing")
	ErrServerShuttingDown      = errors.New("server is shutting down")
	ErrServerNotIdle           = errors.New("server is hosting live workspaces")
	ErrClientRetired           = errors.New("client has been retired")
	ErrChannelOptInMismatch    = errors.New("requested channels differ from the existing workspace; channels are an explicit opt-in and are not shared across duplicate creates")
)

// DefaultCreateGrace is the window in which a client must open an SSE
// stream after creating a workspace before its creation hold is
// released. Exposed as a package variable so tests can shorten it.
var DefaultCreateGrace = 30 * time.Second

// DefaultIdleShutdownDelay is how long the server stays alive after its
// last workspace is released before it shuts itself down. The delay
// exists so a client that closes one session and opens another moments
// later (the same directory or a different one) reuses the still-running
// server instead of racing its shutdown: with an immediate shutdown the
// new client can attach to — or create a workspace on — a server that is
// already tearing down, and then observe its coder agent as "offline".
// Any workspace create within the window cancels the pending shutdown.

View on GitHub (pinned to 7944b8e522)

Solutions

  1. Start a fresh server and retry the workspace create against it
  2. Match with errors.Is(err, client.ErrServerShuttingDown) and treat it as non-transient per server
  3. Increase CRUSH_SERVER_IDLE_TIMEOUT so the server stays up through the create window

Example fix

// before
ws, err := client.CreateWorkspace(ctx, path)
if err != nil { return err }
// after
ws, err := client.CreateWorkspace(ctx, path)
if errors.Is(err, client.ErrServerShuttingDown) {
    return restartServerAndCreate(ctx, path)
}
if err != nil { return err }
Defensive patterns

Strategy: fallback

Type guard

func isErrServerShuttingDown(err error) bool {
    return errors.Is(err, backend.ErrServerShuttingDown) || errors.Is(err, client.ErrServerShuttingDown)
}

Try / catch

ws, err := client.CreateWorkspace(ctx, path)
if errors.Is(err, client.ErrServerShuttingDown) {
    return startNewServerAndCreate(ctx, path) // fallback path
}
return err

Prevention

When it happens

Trigger: CreateWorkspace or any request admitted via admitLocked after shutdown began; createWorkspaceOnLiveServer hitting a server that answered 503; checkStatus receiving http.StatusServiceUnavailable; handleShutdown racing a create.

Common situations: Client reusing a still-running server during its idle shutdown window; a new client starting at the same moment the old server tears down after its last workspace was released; tests shortening DefaultCreateGrace exposing the race.

Related errors

AI-assisted analysis of charmbracelet/crush@7944b8e522 (2026-08-29). Data as JSON: /api/errors/9c434edf89f7107a. Report an issue: GitHub.