Help us shape the future of Go! Take the 2026 Go Developer Survey

errors

package
v1.19.0-rc.6 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 21, 2026 License: Apache-2.0 Imports: 9 Imported by: 0

README

Error codes in Dapr

Introduction

This guide is intended for developers working on the Dapr code base, specifically for those updating the error handling to align with the gRPC richer error model. The goal is to standardize error responses across Dapr's services.

Prerequisites

Step 1: Understanding the Current Error Handling

Currently, error handling in Dapr is a mix of predefined errors and dynamically constructed errors within the code.

  • Predefined Errors: There are some legacy predefined errors located at /pkg/messages/predefined.go, but the new errors are located in /pkg/api/errors. These errors are standard and reused across various parts of the Dapr codebase. They provide a consistent error handling mechanism for common scenarios.
  • Dynamically Constructed Errors: These errors are created on the fly within the code, typically to handle specific situations or errors that are not covered by the predefined set.

As we move predefined errors to the rich error model and a new location (pkg/api/errors), the first step in updating to the new error model is to familiarize yourself with the existing error handling patterns, both predefined and dynamically constructed. This understanding will be crucial when replacing them with the richer error model aligned with gRPC standards.

Step 2: Adding New Errors

  1. Check for existing errors: Before creating a new error, check if a relevant error file exists in /pkg/api/errors/.
  2. Create a new error file: If no relevant file exists, create a new file following the pattern <building-block>.go.

Step 3: Designing Rich Error Messages

  1. Understand Rich Error Construction: Familiarize yourself with the construction of rich error messages. The definition can be found in github.com/dapr/kit/errors.
  2. Helper Methods: Utilize the error builder and the helper methods like WithErrorInfo, WithResourceInfo to enrich error information.
  3. Reference implementation: You can check out pkg/api/errors/state.go for a reference implementation. The following code snippet shows how to create a new error using the helper methods:
func (s *StateStoreError) InvalidKeyName(key string, msg string) error {
	return s.build(
		errors.NewBuilder(
			codes.InvalidArgument,
			http.StatusBadRequest,
			msg,
			"ERR_MALFORMED_REQUEST",
		).WithFieldViolation(key, msg),
		errors.CodeIllegalKey,
		nil,
	)
}
  1. Mandatory and Optional Information:
    • ErrorInfo: This is a required field.
    • ResourceInfo and other Details fields: These are optional but should be used following best practices as outlined in the Google Cloud Error Model.

Step 4: Implementing the New Error Model

  1. Consistent Use: Ensure that the new error model is used consistently throughout the codebase.
  2. Refactoring: Replace existing errors in the code with the newly defined rich errors.

Step 5: Testing and Integration

  1. Integration Tests: Add integration tests for the new error handling mechanism.
  2. Follow Existing Patterns: Use the existing integration tests for the state API as a reference for structure and best practices. For example, these are the integration tests for the errors in state api: /tests/integration/suite/daprd/state/grpc/errors.go and /tests/integration/suite/daprd/state/http/errors.go

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Basic added in v1.15.0 

func Basic(grpcCode codes.Code, httpCode int, errorCode errorcodes.ErrorCode, msg string) error

func Empty added in v1.14.0 

func Empty(name string, metadata map[string]string, errorCode errorcodes.ErrorCode) error

func NotFound 

func NotFound(name string, componentType string, metadata map[string]string, grpcCode codes.Code, httpCode int, legacyTag string, reason string, category errorcodes.Category) error

func PubSubOutbox added in v1.14.0 

func PubSubOutbox(appID string, err error) error

func SchedulerDeleteJob added in v1.14.0 

func SchedulerDeleteJob(metadata map[string]string, err error) error

func SchedulerGetJob added in v1.14.0 

func SchedulerGetJob(metadata map[string]string, err error) error

func SchedulerListJobs added in v1.14.0 

func SchedulerListJobs(metadata map[string]string, err error) error

func SchedulerScheduleJob added in v1.14.0 

func SchedulerScheduleJob(metadata map[string]string, err error) error

func SchedulerURLName added in v1.14.0 

func SchedulerURLName(metadata map[string]string) error

Types

type PubSubError added in v1.14.0 

type PubSubError struct {
	// contains filtered or unexported fields
}

func PubSub added in v1.14.0 

func PubSub(name string) *PubSubError

func (*PubSubError) PublishForbidden added in v1.14.0 

func (p *PubSubError) PublishForbidden(topic, appID string, err error) error

func (*PubSubError) PublishMessage added in v1.14.0 

func (p *PubSubError) PublishMessage(topic string, err error) error

func (*PubSubError) TestNotFound added in v1.14.0 

func (p *PubSubError) TestNotFound(topic string, err error) error

TestNotFound is specifically for the error we are expecting for the api_tests. The not found expected error codes are different than the existing ones for PubSubNotFound, hence why this one is needed

func (*PubSubError) WithAppError added in v1.14.0 

func (p *PubSubError) WithAppError(appID string, err error) *PubSubMetadataError

func (*PubSubError) WithMetadata added in v1.14.0 

func (p *PubSubError) WithMetadata(metadata map[string]string) *PubSubMetadataError

type PubSubMetadataError added in v1.14.0 

type PubSubMetadataError struct {
	// contains filtered or unexported fields
}

func (*PubSubMetadataError) CloudEventCreation added in v1.14.0 

func (p *PubSubMetadataError) CloudEventCreation() error

func (*PubSubMetadataError) DeserializeError added in v1.14.0 

func (p *PubSubMetadataError) DeserializeError(err error) error

func (*PubSubMetadataError) NameEmpty added in v1.14.0 

func (p *PubSubMetadataError) NameEmpty() error

func (*PubSubMetadataError) NotConfigured added in v1.14.0 

func (p *PubSubMetadataError) NotConfigured() error

func (*PubSubMetadataError) NotFound added in v1.14.0 

func (p *PubSubMetadataError) NotFound() error

func (*PubSubMetadataError) TopicEmpty added in v1.14.0 

func (p *PubSubMetadataError) TopicEmpty() error

func (*PubSubMetadataError) WithTopic added in v1.14.0 

func (p *PubSubMetadataError) WithTopic(topic string) *PubSubTopicError

type PubSubTopicError added in v1.14.0 

type PubSubTopicError struct {
	// contains filtered or unexported fields
}

func (*PubSubTopicError) MarshalEnvelope added in v1.14.0 

func (p *PubSubTopicError) MarshalEnvelope() error

func (*PubSubTopicError) MarshalEvents added in v1.14.0 

func (p *PubSubTopicError) MarshalEvents() error

func (*PubSubTopicError) UnmarshalEvents added in v1.14.0 

func (p *PubSubTopicError) UnmarshalEvents(err error) error

UnmarshalEvents only occurs in http/api.go

type SearchStoreError 

type SearchStoreError struct {
	// contains filtered or unexported fields
}

SearchStoreError builds the errors the runtime itself raises for the Search building block.

These builders are for failures the runtime detects on its own: a missing store and request validation performed before the provider is invoked. Errors returned by a component are passed through unchanged instead, because the Search API contract requires the component's canonical google.rpc.Code and any google.rpc.ErrorInfo details (for example the SEARCH_CONTINUATION_EXPIRED and INDEXING_OUTCOME_UNKNOWN reasons) to reach the caller intact.

func SearchStore 

func SearchStore(name string) *SearchStoreError

func (*SearchStoreError) InvalidRequest 

func (s *SearchStoreError) InvalidRequest(field string, msg string) error

InvalidRequest reports request validation the runtime performs before invoking the provider: keyed-upsert IDs that are empty or duplicated, and IndexingOptionsAlpha1 that are invalid or whose wait the store's resiliency timeout cannot accommodate.

func (*SearchStoreError) NotConfigured 

func (s *SearchStoreError) NotConfigured() error

NotConfigured reports a store lookup made when no search store is configured at all.

func (*SearchStoreError) NotFound 

func (s *SearchStoreError) NotFound() error

NotFound reports a store name that does not resolve while other search stores are configured.

type StateStoreError added in v1.14.0 

type StateStoreError struct {
	// contains filtered or unexported fields
}

func StateStore added in v1.14.0 

func StateStore(name string) *StateStoreError

func (*StateStoreError) InvalidKeyName added in v1.14.0 

func (s *StateStoreError) InvalidKeyName(key string, msg string) error

func (*StateStoreError) NotConfigured added in v1.14.0 

func (s *StateStoreError) NotConfigured(appID string) error

func (*StateStoreError) NotFound added in v1.14.0 

func (s *StateStoreError) NotFound(appID string) error

func (*StateStoreError) QueryFailed added in v1.14.0 

func (s *StateStoreError) QueryFailed(detail string) error

func (*StateStoreError) QueryUnsupported added in v1.14.0 

func (s *StateStoreError) QueryUnsupported() error

func (*StateStoreError) TooManyTransactionalOps added in v1.14.0 

func (s *StateStoreError) TooManyTransactionalOps(count int, max int) error

func (*StateStoreError) TransactionsNotSupported added in v1.14.0 

func (s *StateStoreError) TransactionsNotSupported() error

type VectorStoreError 

type VectorStoreError struct {
	// contains filtered or unexported fields
}

func VectorStore 

func VectorStore(name string) *VectorStoreError

func (*VectorStoreError) InvalidRequest 

func (v *VectorStoreError) InvalidRequest(field string, msg string) error

InvalidRequest reports request validation the runtime performs before invoking the provider: keyed-upsert IDs that are empty or duplicated, IndexingOptionsAlpha1 that are invalid or whose wait the store's resiliency timeout cannot accommodate, a vector query that is missing, does not set exactly one of vector / by_id or has an empty vector, and a collection created without dimensions.

func (*VectorStoreError) NotConfigured 

func (v *VectorStoreError) NotConfigured() error

NotConfigured reports a store lookup made when no vector store is configured at all.

func (*VectorStoreError) NotFound 

func (v *VectorStoreError) NotFound() error

NotFound reports a store name that does not resolve while other vector stores are configured.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.