gofr-dev/gofr · critical

status down

Error message

status down

What it means

errStatusDown ('status down') is the sentinel returned by the DynamoDB client's HealthCheck when the datasource fails its health probe (e.g. the AWS DynamoDB client cannot reach the service or an operation check fails). It signals the store is unhealthy, not that a specific key operation failed. Tests reference it to assert error paths.

Source

Thrown at pkg/gofr/datasource/kv-store/dynamodb/dynamo.go:21

import (
	"context"
	"encoding/json"
	"errors"
	"fmt"
	"time"

	"github.com/aws/aws-sdk-go-v2/aws"
	"github.com/aws/aws-sdk-go-v2/config"
	"github.com/aws/aws-sdk-go-v2/service/dynamodb"
	"github.com/aws/aws-sdk-go-v2/service/dynamodb/types"
	"go.opentelemetry.io/otel/attribute"
	"go.opentelemetry.io/otel/trace"
)

var (
	errClientNotConnected = errors.New("client not connected, call Connect() first")
	errKeyNotFound        = errors.New("key not found")
	errStatusDown         = errors.New("status down")
)

type Configs struct {
	Table            string
	Region           string
	Endpoint         string
	PartitionKeyName string
}
type dynamoDBInterface interface {
	PutItem(
		ctx context.Context,
		params *dynamodb.PutItemInput,
		optFns ...func(*dynamodb.Options),
	) (*dynamodb.PutItemOutput, error)
	GetItem(
		ctx context.Context,
		params *dynamodb.GetItemInput,
		optFns ...func(*dynamodb.Options),

View on GitHub (pinned to 187eb24962)

Solutions

1. Fix AWS credentials and region in Configs or environment (AWS_ACCESS_KEY_ID, AWS_REGION, endpoint)
2. If using a custom Configs.Endpoint, confirm the local emulator (e.g. LocalStack) is running and reachable
3. Call Connect() and verify connectivity before health checks; inspect the wrapped cause returned alongside status down
4. Check network egress/IAM policy allows dynamodb operations

// pre-flight: verify AWS config resolves
sess, err := session.NewSession(&aws.Config{Region: aws.String(cfg.Region)})
if err != nil || sess.Config.Region == nil { return fmt.Errorf("invalid AWS config: %w", err) }

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

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

When it happens

Trigger: Calling Client.HealthCheck(ctx) while the AWS credentials/session are invalid, the region/endpoint is wrong, network egress to DynamoDB is blocked, or the underlying DynamoDB client is nil/not connected.

Common situations: Misconfigured AWS_REGION or endpoint in dev containers, missing IAM permissions, corporate proxy/firewall blocking AWS endpoints, LocalStack not running when Configs.Endpoint points at it.

Related errors

• key not found
• %w: %s
• status down
• influxdb health check failed
• status down

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