{"record":{"id":"15668cee9d2e79bc","repo":"gofr-dev/gofr","slug":"handler-error","errorCode":null,"errorMessage":"handler error","messagePattern":"handler error","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/gofr/datasource/pubsub/nats/errors.go","lineNumber":20,"sourceCode":"\nimport \"errors\"\n\nvar (\n\t// Client Errors.\n\terrServerNotProvided       = errors.New(\"client server address not provided\")\n\terrSubjectsNotProvided     = errors.New(\"subjects not provided\")\n\terrConsumerNotProvided     = errors.New(\"consumer name not provided\")\n\terrConsumerCreationError   = errors.New(\"consumer creation error\")\n\terrFailedToDeleteStream    = errors.New(\"failed to delete stream\")\n\terrPublishError            = errors.New(\"publish error\")\n\terrJetStreamNotConfigured  = errors.New(\"jStream is not configured\")\n\terrJetStreamCreationFailed = errors.New(\"jStream creation failed\")\n\terrJetStream               = errors.New(\"jStream error\")\n\terrCreateStream            = errors.New(\"create stream error\")\n\terrDeleteStream            = errors.New(\"delete stream error\")\n\terrGetStream               = errors.New(\"get stream error\")\n\terrCreateOrUpdateStream    = errors.New(\"create or update stream error\")\n\terrHandlerError            = errors.New(\"handler error\")\n\terrConnectionError         = errors.New(\"connection error\")\n\terrSubscriptionError       = errors.New(\"subscription error\")\n)\n","sourceCodeStart":2,"sourceCodeEnd":24,"githubUrl":"https://github.com/gofr-dev/gofr/blob/187eb24962502e91f1fee856230670958b66e89c/pkg/gofr/datasource/pubsub/nats/errors.go#L2-L24","documentation":"errHandlerError (errors.go:20) is the sentinel used in the NATS client's message-fetch/consume path when the registered message handler fails or fetching the next message errors. It wraps handler failures so the consume loop can report them through Query/subscriber error handling. Exercised by TestClient_Query_MessageFetchError.","triggerScenarios":"During Client.Query/subscription consumption: the user-supplied MessageHandler returns an error, or fetching a message from the JetStream consumer fails (message expired/deleted, consumer detached).","commonSituations":"Handler panics or returns errors on malformed payloads (JSON decode failures); messages redelivered after AckWait with consumers in a bad state; consumer deleted server-side while fetching.","solutions":["Make your message handler defensive: validate/decode payloads and return errors only for genuine failures.","Check the wrapped cause to distinguish a handler bug from a fetch/consumer failure.","Recreate or reset the consumer if it was deleted or detached server-side (`nats consumer info <stream> <consumer>`).","Add dead-letter/NAK handling for poison messages instead of failing the loop repeatedly."],"exampleFix":"// before: handler errors on bad payload\nhandler := func(ctx context.Context, m pubsub.Message) error {\n    var o Order; return json.Unmarshal(m.Value(), &o)\n}\n// after: tolerate malformed messages\nif err := json.Unmarshal(m.Value(), &o); err != nil {\n    logger.Errorf(\"skipping malformed message: %v\", err)\n    return nil\n}","handlingStrategy":"try-catch","validationCode":"// validate handler behavior before registering\nif handler == nil {\n    return errors.New(\"message handler must not be nil\")\n}","typeGuard":null,"tryCatchPattern":"handler := func(ctx context.Context, m pubsub.Message) error {\n    defer func() {\n        if r := recover(); r != nil {\n            logger.Errorf(\"handler panic: %v\", r)\n        }\n    }()\n    return process(ctx, m)\n}","preventionTips":["Validate/decode payloads inside the handler; return nil for poison messages after logging.","Recover from panics in the handler so one bad message doesn't kill consumption.","Monitor consumer state (`nats consumer info`) for detached/deleted consumers.","Set sensible AckWait/MaxDeliver and dead-letter flows for redelivery storms."],"tags":["nats","jetstream","consumer","message-handler","gofr"],"backgroundTag":"message-handler-failed","analyzedSha":"187eb24962502e91f1fee856230670958b66e89c","analyzedAt":"2026-09-01T20:34:54.554Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}