gofr-dev/gofr · critical

status down

Error message

status down

What it means

In the NATS KV-store client, errStatusDown ('status down') is the sentinel returned by HealthCheck when the JetStream key-value bucket or the NATS connection is unavailable. It reports the datasource as unhealthy so monitoring can flag it.

Source

Thrown at pkg/gofr/datasource/kv-store/nats/nats.go:15

package nats

import (
	"context"
	"errors"
	"fmt"
	"time"

	"github.com/nats-io/nats.go"
	"go.opentelemetry.io/otel/attribute"
	"go.opentelemetry.io/otel/trace"
)

var (
	errStatusDown  = errors.New("status down")
	errKeyNotFound = errors.New("key not found")
)

type Configs struct {
	Server string
	Bucket string
}

type jetStream struct {
	nats.JetStreamContext
}

func (j jetStream) AccountInfo() (*nats.AccountInfo, error) {
	return j.JetStreamContext.AccountInfo()
}

type Client struct {
	conn    *nats.Conn

View on GitHub (pinned to 187eb24962)

Solutions

1. Verify Configs.Server points to a reachable NATS server (nats://host:4222)
2. Confirm the JetStream bucket exists: nats kv info <bucket>, or create it before use
3. Reconnect/retry; inspect the wrapped cause for the underlying NATS error
4. Check the server has JetStream enabled (--js flag)

// pre-flight connectivity probe
nc, err := nats.Connect(cfg.Server, nats.Timeout(3*time.Second))
if err != nil { return fmt.Errorf("nats unreachable: %w", err) }
js, _ := nc.JetStream()
if _, err := js.KeyValue(cfg.Bucket); err != nil { return fmt.Errorf("bucket %q missing: %w", cfg.Bucket, err) }

func IsStatusDown(err error) bool { return errors.Is(err, natskv.ErrStatusDown) }

if err := store.HealthCheck(ctx); err != nil {
    if errors.Is(err, natskv.ErrStatusDown) {
        return retry.WithBackoff(store.HealthCheck, 5*time.Second)
    }
    return err
}

When it happens

Trigger: HealthCheck called while the NATS server is unreachable, the client was never connected, the configured Bucket does not exist in JetStream, or the JetStream stream backing the bucket was deleted.

Common situations: NATS server down or wrong Server URL/port, bucket name typo, JetStream disabled on the server, bucket deleted by max-age limits or manually.

Related errors

• failed to get key: %w
• jStream error
• status down
• key not found
• %w: %s

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