What causes "%w: %v" in charmbracelet/crush?

Send a proper UUIDv4 string as the client ID (e.g. uuid.New().String())

ErrInvalidClientID

ErrInvalidClientID

Error message

%w: %v

What it means

validateClientID checks that a client-supplied ID is a non-empty valid UUID. An empty string returns bare ErrInvalidClientID; a non-empty but unparseable value returns ErrInvalidClientID wrapped with the uuid parse error via %w, so callers can errors.Is against ErrInvalidClientID.

Source

Thrown at internal/backend/backend.go:1064

func resolveWorkspaceKey(path string) (string, error) {
	abs, err := filepath.Abs(path)
	if err != nil {
		return "", err
	}
	if resolved, err := filepath.EvalSymlinks(abs); err == nil {
		return resolved, nil
	}
	return abs, nil
}

// validateClientID returns the trimmed UUID string or an error if the
// input is empty or not a valid UUID.
func validateClientID(id string) (string, error) {
	if id == "" {
		return "", ErrInvalidClientID
	}
	if _, err := uuid.Parse(id); err != nil {
		return "", fmt.Errorf("%w: %v", ErrInvalidClientID, err)
	}
	return id, nil
}

func workspaceToProto(ws *Workspace) proto.Workspace {
	cfg := ws.Cfg.Config()
	out := proto.Workspace{
		ID:       ws.ID,
		Path:     ws.Path,
		YOLO:     ws.Cfg.Overrides().SkipPermissionRequests,
		Channels: ws.Cfg.Overrides().EnabledChannels,
		DataDir:  cfg.Options.DataDirectory,
		Debug:    cfg.Options.Debug,
		Config:   cfg,
		Env:      ws.Env,
		Version:  version.Version,
	}
	if ws.Skills != nil {

View on GitHub (pinned to 7944b8e522)

Solutions

Send a proper UUIDv4 string as the client ID (e.g. uuid.New().String())
Check the client is not sending an empty/unset ID field
Confirm you're not confusing session IDs with client IDs

Example fix

// before
clientID := "my-client-1"
// after
clientID := uuid.New().String()

Defensive patterns

Strategy: validation

Validate before calling

func validClientID(id string) bool {
    if id == "" {
        return false
    }
    _, err := uuid.Parse(id)
    return err == nil
}

Type guard

func isValidUUID(s string) bool {
    if s == "" {
        return false
    }
    _, err := uuid.Parse(s)
    return err == nil
}

Try / catch

if _, err := b.AttachClient(ctx, clientID); err != nil {
    if errors.Is(err, backend.ErrInvalidClientID) {
        return fmt.Errorf("client ID must be a non-empty UUID: %w", err)
    }
    return err
}

Prevention

Generate client IDs with uuid.New().String()
Never pass session IDs or custom slugs where a client UUID is expected
Validate UUID format on the client before sending RPCs

When it happens

Trigger: CreateWorkspace, AttachClient, RetireClient, releaseHold, or SetCurrentSession called with an empty or malformed client ID string (e.g. 'abc', truncated UUID, wrong casing is fine but wrong format is not).

Common situations: Client generates IDs with a non-UUID scheme; passing a session ID where a client ID is expected; empty field in an RPC payload; hand-crafted requests against the backend API.

Related errors

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