What causes "jStream error" in gofr-dev/gofr?

Inspect the wrapped cause to identify the concrete JetStream failure (errors.Unwrap / %w chain).

jStream error

Error message

jStream error

What it means

errJetStream (errors.go:15) is the generic "jStream error" sentinel returned by jetStream()/validateJetStream when obtaining or validating the JetStream handle fails for reasons other than it simply being unconfigured. It wraps or accompanies underlying JetStream failures surfaced through Query/GetJetStreamStatus paths and health checks.

Source

Thrown at pkg/gofr/datasource/pubsub/nats/errors.go:15

package nats

import "errors"

var (
	// Client Errors.
	errServerNotProvided       = errors.New("client server address not provided")
	errSubjectsNotProvided     = errors.New("subjects not provided")
	errConsumerNotProvided     = errors.New("consumer name not provided")
	errConsumerCreationError   = errors.New("consumer creation error")
	errFailedToDeleteStream    = errors.New("failed to delete stream")
	errPublishError            = errors.New("publish error")
	errJetStreamNotConfigured  = errors.New("jStream is not configured")
	errJetStreamCreationFailed = errors.New("jStream creation failed")
	errJetStream               = errors.New("jStream error")
	errCreateStream            = errors.New("create stream error")
	errDeleteStream            = errors.New("delete stream error")
	errGetStream               = errors.New("get stream error")
	errCreateOrUpdateStream    = errors.New("create or update stream error")
	errHandlerError            = errors.New("handler error")
	errConnectionError         = errors.New("connection error")
	errSubscriptionError       = errors.New("subscription error")
)

View on GitHub (pinned to 187eb24962)

Solutions

Inspect the wrapped cause to identify the concrete JetStream failure (errors.Unwrap / %w chain).
Verify the referenced stream still exists (`nats stream info <name>`) — deleted streams surface as generic JS errors.
Check server health and disk/memory usage; JS returns errors when storage limits are hit.
Reconnect the client (retry Connect) if the connection dropped after JetStream was initialized.

Example fix

// before: ignoring health-check errors
status, _ := client.Query(ctx)
// after: handle jetStream failure and reconnect
if err != nil {
    logger.Errorf("jetstream error: %v", err)
    _ = client.Connect()
}

Defensive patterns

Strategy: try-catch

Validate before calling

if js == nil {
    return errors.New("jetstream handle missing")
}
if err := js.Singleton(ctx) == nil; false {
}

Try / catch

status, err := client.Query(ctx)
if err != nil {
    if errors.Is(err, errJetStream) {
        logger.Errorf("jetstream degraded: %v", err)
        // mark unhealthy and trigger reconnect
    }
    return err
}

Prevention

Use the client health endpoint/Query in readiness probes.
Watch NATS disconnect/reconnect callbacks and reset JetStream state.
Monitor server storage/memory limits that trigger JS errors.
Log the wrapped cause, not just the sentinel.

When it happens

Trigger: Client.Query or health/status checks hitting a JetStream operation that errors (e.g. getting stream info) while the handle is present; validateJetStream failing after Connect; exercised by TestClient_Query_JetStreamError and TestClient_GetJetStreamStatus.

Common situations: JetStream temporarily unavailable mid-operation (server restarting, storage full); stream deleted while querying its status; connectivity dropped between connect and first JetStream call.

Related errors

AI-assisted analysis of gofr-dev/gofr@187eb24962 (2026-09-01). Data as JSON: /api/errors/ff3d2d217286a026. Report an issue: GitHub.