charmbracelet/crush · error

failed to create session: status code %d

Error message

failed to create session: status code %d

What it means

CreateSession reached the server but received a non-200 status code for the POST to /workspaces/{id}/sessions. The status code is embedded in the error. Common codes: 400 (invalid title/payload), 401/403 (auth), 404 (workspace not found), 409/422 (validation), 5xx (server error).

Source

Thrown at internal/client/proto.go:649

	if rsp.StatusCode != http.StatusOK {
		return nil, fmt.Errorf("failed to get session history files: status code %d", rsp.StatusCode)
	}
	var files []proto.File
	if err := json.NewDecoder(rsp.Body).Decode(&files); err != nil {
		return nil, fmt.Errorf("failed to decode session history files: %w", err)
	}
	return files, nil
}

// CreateSession creates a new session in a workspace as a proto type.
func (c *Client) CreateSession(ctx context.Context, id string, title string) (*proto.Session, error) {
	rsp, err := c.post(ctx, fmt.Sprintf("/workspaces/%s/sessions", id), nil, jsonBody(proto.Session{Title: title}), http.Header{"Content-Type": []string{"application/json"}})
	if err != nil {
		return nil, fmt.Errorf("failed to create session: %w", err)
	}
	defer rsp.Body.Close()
	if rsp.StatusCode != http.StatusOK {
		return nil, fmt.Errorf("failed to create session: status code %d", rsp.StatusCode)
	}
	var sess proto.Session
	if err := json.NewDecoder(rsp.Body).Decode(&sess); err != nil {
		return nil, fmt.Errorf("failed to decode session: %w", err)
	}
	return &sess, nil
}

// ListSessions lists all sessions in a workspace as proto types.
func (c *Client) ListSessions(ctx context.Context, id string) ([]proto.Session, error) {
	rsp, err := c.get(ctx, fmt.Sprintf("/workspaces/%s/sessions", id), nil, nil)
	if err != nil {
		return nil, fmt.Errorf("failed to get sessions: %w", err)
	}
	defer rsp.Body.Close()
	if rsp.StatusCode != http.StatusOK {
		return nil, fmt.Errorf("failed to get sessions: status code %d", rsp.StatusCode)
	}

View on GitHub (pinned to 7944b8e522)

Solutions

  1. Read the status code from the error and branch on it (404: fix workspace ID; 401/403: refresh credentials; 400: validate title).
  2. Ensure the title is non-empty and within server limits.
  3. Verify the workspace ID exists via the API.
  4. Re-authenticate if credentials expired.
  5. Retry with backoff on 429/5xx.

Example fix

// before
sess, err := client.CreateSession(ctx, wsID, title)
if err != nil { return err }
// after
if title == "" { return errors.New("session title must not be empty") }
sess, err := client.CreateSession(ctx, wsID, title)
if err != nil {
    if strings.Contains(err.Error(), "status code 404") {
        return fmt.Errorf("workspace %q not found", wsID)
    }
    return err
}
Defensive patterns

Strategy: validation

Validate before calling

if strings.TrimSpace(title) == "" {
    return errors.New("session title must not be empty")
}
if _, err := client.GetWorkspace(ctx, wsID); err != nil {
    return fmt.Errorf("workspace %q invalid: %w", wsID, err)
}

Type guard

func isCreateStatusError(err error, code int) bool {
    return err != nil && strings.Contains(err.Error(), "failed to create session: status code "+strconv.Itoa(code))
}

Try / catch

sess, err := client.CreateSession(ctx, wsID, title)
if err != nil {
    switch {
    case isCreateStatusError(err, 400):
        return fmt.Errorf("invalid session payload (title=%q)", title)
    case isCreateStatusError(err, 404):
        return fmt.Errorf("workspace %q not found", wsID)
    case isCreateStatusError(err, 401), isCreateStatusError(err, 403):
        return fmt.Errorf("re-authenticate: %w", err)
    }
    return err
}

Prevention

When it happens

Trigger: POST /workspaces/{id}/sessions returns 400 for an empty or invalid title, 401/403 for bad credentials, 404 for a nonexistent workspace ID, or 5xx on server failure.

Common situations: Creating a session with an empty title; using a workspace ID that does not exist; expired auth token; server rejecting the payload due to schema changes.

Related errors

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