What causes "failed to create session: %w" in charmbracelet/crush?

Inspect the wrapped error for the root cause.

failed to create session: %w

Error message

failed to create session: %w

What it means

CreateSession failed inside c.post, the low-level HTTP helper, before a response was returned. The transport error is wrapped with this message. The POST to /workspaces/{id}/sessions never completed: connection failure, TLS error, or context cancellation.

Source

Thrown at internal/client/proto.go:645

	if err != nil {
		return nil, fmt.Errorf("failed to get session history files: %w", err)
	}
	defer rsp.Body.Close()
	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)
	}

View on GitHub (pinned to 7944b8e522)

Solutions

Inspect the wrapped error for the root cause.
Verify server availability and the workspace ID.
Retry with backoff for transient network failures; note the session may or may not have been created, so check via ListSessions/GetSession before retrying blindly.
Check context deadlines — allow enough time for session creation.
Confirm network/VPN/TLS setup.

Example fix

// before
sess, err := client.CreateSession(ctx, wsID, title)
if err != nil { return err }
// after
sess, err := client.CreateSession(ctx, wsID, title)
if err != nil {
    if ctx.Err() != nil { return ctx.Err() }
    // transient? retry idempotently: look up by title first
    return err
}

Defensive patterns

Strategy: retry

Validate before calling

// Validate inputs and connectivity first
if wsID == "" { return errors.New("workspace id required") }
if err := ctx.Err(); err != nil { return err }

Type guard

func isCreateTransportError(err error) bool {
    var netErr net.Error
    return err != nil && strings.Contains(err.Error(), "failed to create session") && errors.As(err, &netErr)
}

Try / catch

sess, err := client.CreateSession(ctx, wsID, title)
if err != nil {
    if ctx.Err() != nil { return ctx.Err() }
    // transport-level: safe to retry after checking whether the session was created
    return retryWithBackoff(func() error {
        s, e := client.CreateSession(ctx, wsID, title)
        if e == nil { sess = s; return nil }
        return e
    })
}

Prevention

Use contexts with adequate deadlines.
Verify server availability before writes.
Treat create retries carefully — list sessions to avoid duplicates.
Escape IDs used in URL paths.

When it happens

Trigger: POST /workspaces/{id}/sessions fails at transport level: server down, connection refused/reset, ctx deadline exceeded, or URL-escaping issues with the workspace id.

Common situations: Server unreachable (wrong host/port); network interruption during the POST; caller's context cancelled while creating the session; oversized or invalid title causing early connection teardown (rare).

Understand the failure class

Background: 'Something went wrong' / 'Request failed (500)' / 'HTTP error! status: 404' — what failed HTTP requests actually mean and how to find the real cause — this error's family across 28 libraries.

Related errors

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