feat(go): use GenkitError instead of regular error (#2643)

Author: sahdev77

go/ai/gen.go

@@ -181,23 +181,6 @@ type GenerationUsage struct {
 	TotalTokens      int                `json:"totalTokens,omitempty"`
 }
 
-type GenkitError struct {
-	Data    *GenkitErrorData `json:"data,omitempty"`
-	Details any              `json:"details,omitempty"`
-	Message string           `json:"message,omitempty"`
-	Stack   string           `json:"stack,omitempty"`
-}
-
-type GenkitErrorData struct {
-	GenkitErrorDetails *GenkitErrorDetails `json:"genkitErrorDetails,omitempty"`
-	GenkitErrorMessage string              `json:"genkitErrorMessage,omitempty"`
-}
-
-type GenkitErrorDetails struct {
-	Stack   string `json:"stack,omitempty"`
-	TraceID string `json:"traceId,omitempty"`
-}
-
 type Media struct {
 	ContentType string `json:"contentType,omitempty"`
 	Url         string `json:"url,omitempty"`

go/ai/generate.go

@@ -153,7 +153,7 @@ func LookupModel(r *registry.Registry, provider, name string) Model {
 // It returns an error if the model was not defined.
 func LookupModelByName(r *registry.Registry, modelName string) (Model, error) {
 	if modelName == "" {
-		return nil, errors.New("ai.LookupModelByName: model not specified")
+		return nil, core.NewError(core.INVALID_ARGUMENT, "ai.LookupModelByName: model not specified")
 	}
 
 	provider, name, found := strings.Cut(modelName, "/")
@@ -165,9 +165,9 @@ func LookupModelByName(r *registry.Registry, modelName string) (Model, error) {
 	model := LookupModel(r, provider, name)
 	if model == nil {
 		if provider == "" {
-			return nil, fmt.Errorf("ai.LookupModelByName: no model named %q", name)
+			return nil, core.NewError(core.NOT_FOUND, "ai.LookupModelByName: model %q not found", name)
 		}
-		return nil, fmt.Errorf("ai.LookupModelByName: no model named %q for provider %q", name, provider)
+		return nil, core.NewError(core.NOT_FOUND, "ai.LookupModelByName: model %q by provider %q not found", name, provider)
 	}
 
 	return model, nil
@@ -180,7 +180,7 @@ func GenerateWithRequest(ctx context.Context, r *registry.Registry, opts *Genera
 			opts.Model = defaultModel
 		}
 		if opts.Model == "" {
-			return nil, errors.New("ai.GenerateWithRequest: model is required")
+			return nil, core.NewError(core.INVALID_ARGUMENT, "ai.GenerateWithRequest: model is required")
 		}
 	}
 
@@ -193,12 +193,12 @@ func GenerateWithRequest(ctx context.Context, r *registry.Registry, opts *Genera
 	toolDefMap := make(map[string]*ToolDefinition)
 	for _, t := range opts.Tools {
 		if _, ok := toolDefMap[t]; ok {
-			return nil, fmt.Errorf("ai.GenerateWithRequest: duplicate tool found: %q", t)
+			return nil, core.NewError(core.INVALID_ARGUMENT, "ai.GenerateWithRequest: duplicate tool %q", t)
 		}
 
 		tool := LookupTool(r, t)
 		if tool == nil {
-			return nil, fmt.Errorf("ai.GenerateWithRequest: tool not found: %q", t)
+			return nil, core.NewError(core.NOT_FOUND, "ai.GenerateWithRequest: tool %q not found", t)
 		}
 
 		toolDefMap[t] = tool.Definition()
@@ -210,7 +210,7 @@ func GenerateWithRequest(ctx context.Context, r *registry.Registry, opts *Genera
 
 	maxTurns := opts.MaxTurns
 	if maxTurns < 0 {
-		return nil, fmt.Errorf("ai.GenerateWithRequest: max turns must be greater than 0, got %d", maxTurns)
+		return nil, core.NewError(core.INVALID_ARGUMENT, "ai.GenerateWithRequest: max turns must be greater than 0, got %d", maxTurns)
 	}
 	if maxTurns == 0 {
 		maxTurns = 5 // Default max turns.
@@ -276,7 +276,8 @@ func GenerateWithRequest(ctx context.Context, r *registry.Registry, opts *Genera
 			resp.Message, err = formatHandler.ParseMessage(resp.Message)
 			if err != nil {
 				logger.FromContext(ctx).Debug("model failed to generate output matching expected schema", "error", err.Error())
-				return nil, fmt.Errorf("model failed to generate output matching expected schema: %w", err)
+				return nil, core.NewError(core.INTERNAL, "model failed to generate output matching expected schema: %v", err)
+
 			}
 		}
 
@@ -291,7 +292,7 @@ func GenerateWithRequest(ctx context.Context, r *registry.Registry, opts *Genera
 		}
 
 		if currentTurn+1 > maxTurns {
-			return nil, fmt.Errorf("exceeded maximum tool call iterations (%d)", maxTurns)
+			return nil, core.NewError(core.ABORTED, "exceeded maximum tool call iterations (%d)", maxTurns)
 		}
 
 		newReq, interruptMsg, err := handleToolRequests(ctx, r, req, resp, cb)
@@ -318,7 +319,7 @@ func Generate(ctx context.Context, r *registry.Registry, opts ...GenerateOption)
 	genOpts := &generateOptions{}
 	for _, opt := range opts {
 		if err := opt.applyGenerate(genOpts); err != nil {
-			return nil, fmt.Errorf("ai.Generate: error applying options: %w", err)
+			return nil, core.NewError(core.INVALID_ARGUMENT, "ai.Generate: error applying options: %v", err)
 		}
 	}
 
@@ -421,7 +422,7 @@ func (m *model) Name() string {
 // Generate applies the [Action] to provided request.
 func (m *model) Generate(ctx context.Context, req *ModelRequest, cb ModelStreamCallback) (*ModelResponse, error) {
 	if m == nil {
-		return nil, errors.New("Model.Generate: generate called on a nil model; check that all models are defined")
+		return nil, core.NewError(core.INVALID_ARGUMENT, "Model.Generate: generate called on a nil model; check that all models are defined")
 	}
 
 	return (*core.ActionDef[*ModelRequest, *ModelResponse, *ModelResponseChunk])(m).Run(ctx, req, cb)
@@ -478,12 +479,12 @@ func cloneMessage(m *Message) *Message {
 		panic(fmt.Sprintf("failed to marshal message: %v", err))
 	}
 
-	var copy Message
-	if err := json.Unmarshal(bytes, &copy); err != nil {
+	var msgCopy Message
+	if err := json.Unmarshal(bytes, &msgCopy); err != nil {
 		panic(fmt.Sprintf("failed to unmarshal message: %v", err))
 	}
 
-	return &copy
+	return &msgCopy
 }
 
 // handleToolRequests processes any tool requests in the response, returning
@@ -520,7 +521,7 @@ func handleToolRequests(ctx context.Context, r *registry.Registry, req *ModelReq
 			toolReq := p.ToolRequest
 			tool := LookupTool(r, toolReq.Name)
 			if tool == nil {
-				resultChan <- toolResult{idx, nil, fmt.Errorf("tool %q not found", toolReq.Name)}
+				resultChan <- toolResult{idx, nil, core.NewError(core.NOT_FOUND, "tool %q not found", toolReq.Name)}
 				return
 			}
 
@@ -538,7 +539,7 @@ func handleToolRequests(ctx context.Context, r *registry.Registry, req *ModelReq
 					resultChan <- toolResult{idx, nil, interruptErr}
 					return
 				}
-				resultChan <- toolResult{idx, nil, fmt.Errorf("tool %q failed: %w", toolReq.Name, err)}
+				resultChan <- toolResult{idx, nil, core.NewError(core.INTERNAL, "tool %q failed: %v", toolReq.Name, err)}
 				return
 			}
 

go/ai/model_middleware.go

@@ -27,6 +27,7 @@ import (
 	"strconv"
 	"strings"
 
+	"github.com/firebase/genkit/go/core"
 	"github.com/firebase/genkit/go/core/logger"
 )
 
@@ -101,28 +102,28 @@ func validateSupport(model string, info *ModelInfo) ModelMiddleware {
 				for _, msg := range input.Messages {
 					for _, part := range msg.Content {
 						if part.IsMedia() {
-							return nil, fmt.Errorf("model %q does not support media, but media was provided. Request: %+v", model, input)
+							return nil, core.NewError(core.INVALID_ARGUMENT, "model %q does not support media, but media was provided. Request: %+v", model, input)
 						}
 					}
 				}
 			}
 
 			if !info.Supports.Tools && len(input.Tools) > 0 {
-				return nil, fmt.Errorf("model %q does not support tool use, but tools were provided. Request: %+v", model, input)
+				return nil, core.NewError(core.INVALID_ARGUMENT, "model %q does not support tool use, but tools were provided. Request: %+v", model, input)
 			}
 
 			if !info.Supports.Multiturn && len(input.Messages) > 1 {
-				return nil, fmt.Errorf("model %q does not support multiple messages, but %d were provided. Request: %+v", model, len(input.Messages), input)
+				return nil, core.NewError(core.INVALID_ARGUMENT, "model %q does not support multiple messages, but %d were provided. Request: %+v", model, len(input.Messages), input)
 			}
 
 			if !info.Supports.ToolChoice && input.ToolChoice != "" && input.ToolChoice != ToolChoiceAuto {
-				return nil, fmt.Errorf("model %q does not support tool choice, but tool choice was provided. Request: %+v", model, input)
+				return nil, core.NewError(core.INVALID_ARGUMENT, "model %q does not support tool choice, but tool choice was provided. Request: %+v", model, input)
 			}
 
 			if !info.Supports.SystemRole {
 				for _, msg := range input.Messages {
 					if msg.Role == RoleSystem {
-						return nil, fmt.Errorf("model %q does not support system role, but system role was provided. Request: %+v", model, input)
+						return nil, core.NewError(core.INVALID_ARGUMENT, "model %q does not support system role, but system role was provided. Request: %+v", model, input)
 					}
 				}
 			}
@@ -140,7 +141,7 @@ func validateSupport(model string, info *ModelInfo) ModelMiddleware {
 				info.Supports.Constrained == ConstrainedSupportNone ||
 				(info.Supports.Constrained == ConstrainedSupportNoTools && len(input.Tools) > 0)) &&
 				input.Output != nil && input.Output.Constrained {
-				return nil, fmt.Errorf("model %q does not support native constrained output, but constrained output was requested. Request: %+v", model, input)
+				return nil, core.NewError(core.INVALID_ARGUMENT, "model %q does not support native constrained output, but constrained output was requested. Request: %+v", model, input)
 			}
 
 			if err := validateVersion(model, info.Versions, input.Config); err != nil {
@@ -176,14 +177,14 @@ func validateVersion(model string, versions []string, config any) error {
 
 	version, ok := versionVal.(string)
 	if !ok {
-		return fmt.Errorf("version must be a string, got %T", versionVal)
+		return core.NewError(core.INVALID_ARGUMENT, "version must be a string, got %T", versionVal)
 	}
 
 	if slices.Contains(versions, version) {
 		return nil
 	}
 
-	return fmt.Errorf("model %q does not support version %q, supported versions: %v", model, version, versions)
+	return core.NewError(core.INVALID_ARGUMENT, "model %q does not support version %q, supported versions: %v", model, version, versions)
 }
 
 // ContextItemTemplate is the default item template for context augmentation.
@@ -302,13 +303,13 @@ func DownloadRequestMedia(options *DownloadMediaOptions) ModelMiddleware {
 
 					resp, err := client.Get(mediaUrl)
 					if err != nil {
-						return nil, fmt.Errorf("HTTP error downloading media %q: %w", mediaUrl, err)
+						return nil, core.NewError(core.INVALID_ARGUMENT, "HTTP error downloading media %q: %v", mediaUrl, err)
 					}
 					defer resp.Body.Close()
 
 					if resp.StatusCode != http.StatusOK {
 						body, _ := io.ReadAll(resp.Body)
-						return nil, fmt.Errorf("HTTP error downloading media %q: %s", mediaUrl, string(body))
+						return nil, core.NewError(core.UNKNOWN, "HTTP error downloading media %q: %s", mediaUrl, string(body))
 					}
 
 					contentType := part.ContentType
@@ -324,7 +325,7 @@ func DownloadRequestMedia(options *DownloadMediaOptions) ModelMiddleware {
 						data, err = io.ReadAll(resp.Body)
 					}
 					if err != nil {
-						return nil, fmt.Errorf("error reading media %q: %v", mediaUrl, err)
+						return nil, core.NewError(core.UNKNOWN, "error reading media %q: %v", mediaUrl, err)
 					}
 
 					message.Content[j] = NewMediaPart(contentType, fmt.Sprintf("data:%s;base64,%s", contentType, base64.StdEncoding.EncodeToString(data)))

go/core/action.go

@@ -20,7 +20,6 @@ import (
 	"context"
 	"encoding/json"
 	"fmt"
-	"net/http"
 	"reflect"
 	"time"
 
@@ -213,7 +212,7 @@ func (a *ActionDef[In, Out, Stream]) Run(ctx context.Context, input In, cb Strea
 func (a *ActionDef[In, Out, Stream]) RunJSON(ctx context.Context, input json.RawMessage, cb StreamCallback[json.RawMessage]) (json.RawMessage, error) {
 	// Validate input before unmarshaling it because invalid or unknown fields will be discarded in the process.
 	if err := base.ValidateJSON(input, a.inputSchema); err != nil {
-		return nil, &base.HTTPError{Code: http.StatusBadRequest, Err: err}
+		return nil, NewError(INVALID_ARGUMENT, err.Error())
 	}
 	var in In
 	if input != nil {

go/core/error.go

@@ -0,0 +1,120 @@
+// Copyright 2025 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+// SPDX-License-Identifier: Apache-2.0
+
+// Package core provides base error types and utilities for Genkit.
+package core
+
+import (
+	"fmt"
+	"runtime/debug"
+)
+
+type ReflectionErrorDetails struct {
+	Stack   *string `json:"stack,omitempty"` // Use pointer for optional
+	TraceID *string `json:"traceId,omitempty"`
+}
+
+// ReflectionError is the wire format for HTTP errors for Reflection API responses.
+type ReflectionError struct {
+	Details *ReflectionErrorDetails `json:"details,omitempty"`
+	Message string                  `json:"message"`
+	Code    int                     `json:"code"`
+}
+
+// GenkitError is the base error type for Genkit errors.
+type GenkitError struct {
+	Message  string         `json:"message"` // Exclude from default JSON if embedded elsewhere
+	Status   StatusName     `json:"status"`
+	HTTPCode int            `json:"-"`                // Exclude from default JSON
+	Details  map[string]any `json:"details"`          // Use map for arbitrary details
+	Source   *string        `json:"source,omitempty"` // Pointer for optional
+}
+
+// UserFacingError is the base error type for user facing errors.
+type UserFacingError struct {
+	Message string         `json:"message"` // Exclude from default JSON if embedded elsewhere
+	Status  StatusName     `json:"status"`
+	Details map[string]any `json:"details"` // Use map for arbitrary details
+}
+
+// NewPublicError allows a web framework handler to know it
+// is safe to return the message in a request. Other kinds of errors will
+// result in a generic 500 message to avoid the possibility of internal
+// exceptions being leaked to attackers.
+func NewPublicError(status StatusName, message string, details map[string]any) *UserFacingError {
+	return &UserFacingError{
+		Status:  status,
+		Details: details,
+		Message: message,
+	}
+}
+
+// Error implements the standard error interface for UserFacingError.
+func (e *UserFacingError) Error() string {
+	return fmt.Sprintf("%s: %s", e.Status, e.Message)
+}
+
+// NewError creates a new GenkitError with a stack trace.
+func NewError(status StatusName, message string, args ...any) *GenkitError {
+	// Prevents a compile-time warning about non-constant message.
+	msg := message
+
+	ge := &GenkitError{
+		Status:  status,
+		Message: fmt.Sprintf(msg, args...),
+	}
+
+	errStack := string(debug.Stack())
+	if errStack != "" {
+		ge.Details = make(map[string]any)
+		ge.Details["stack"] = errStack
+	}
+	return ge
+}
+
+// Error implements the standard error interface.
+func (e *GenkitError) Error() string {
+	return e.Message
+}
+
+// ToReflectionError returns a JSON-serializable representation for reflection API responses.
+func (e *GenkitError) ToReflectionError() ReflectionError {
+	errDetails := &ReflectionErrorDetails{}
+	if stackVal, ok := e.Details["stack"].(string); ok {
+		errDetails.Stack = &stackVal
+	}
+	if traceVal, ok := e.Details["traceId"].(string); ok {
+		errDetails.TraceID = &traceVal
+	}
+	return ReflectionError{
+		Details: errDetails,
+		Code:    HTTPStatusCode(e.Status),
+		Message: e.Message,
+	}
+}
+
+// ToReflectionError gets the JSON representation for reflection API Error responses.
+func ToReflectionError(err error) ReflectionError {
+	if ge, ok := err.(*GenkitError); ok {
+		return ge.ToReflectionError()
+	}
+
+	return ReflectionError{
+		Message: err.Error(),
+		Code:    HTTPStatusCode(INTERNAL),
+		Details: &ReflectionErrorDetails{},
+	}
+}

go/core/schemas.config

@@ -272,4 +272,6 @@ Score                                   omit
 
 Embedding.embedding                     type []float32
 
-GenkitErrorDataGenkitErrorDetails       name GenkitErrorDetails
+GenkitError                             omit
+GenkitErrorData                         omit
+GenkitErrorDataGenkitErrorDetails       omit