gofr-dev/gofr · error

failed to list objects

Error message

failed to list objects

What it means

errFailedToListObjects is returned by ListObjects when a directory listing (LIST/MLSD) fails on the FTP server. It wraps the underlying goftp error from the listing command. Callers should distinguish it from an empty (but successful) listing.

Source

Thrown at pkg/gofr/datasource/file/ftp/storage_adapter.go:30

	"github.com/jlaffaye/ftp"
	"gofr.dev/pkg/gofr/datasource/file"
)

var (
	// Storage adapter errors.
	errFTPConfigNil            = errors.New("FTP config is nil")
	errFTPClientNotInitialized = errors.New("FTP client is not initialized")
	errEmptyObjectName         = errors.New("object name is empty")
	errInvalidOffset           = errors.New("invalid offset: must be >= 0")
	errEmptySourceOrDest       = errors.New("source and destination names cannot be empty")
	errSameSourceAndDest       = errors.New("source and destination are the same")
	errFailedToCreateReader    = errors.New("failed to create reader")
	errFailedToCreateWriter    = errors.New("failed to create writer")
	errObjectNotFound          = errors.New("object not found")
	errFailedToGetObjectAttrs  = errors.New("failed to get object attrs")
	errFailedToDeleteObject    = errors.New("failed to delete object")
	errFailedToListObjects     = errors.New("failed to list objects")
	errFailedToListDirectory   = errors.New("failed to list directory")
	errWriterAlreadyClosed     = errors.New("writer already closed")
	errFTPConfigInvalid        = errors.New("invalid FTP configuration: host and port are required")
)

// Config represents the FTP configuration.
type Config struct {
	Host        string        // FTP server hostname
	User        string        // FTP username
	Password    string        // FTP password
	Port        int           // FTP port
	RemoteDir   string        // Remote directory path. Base Path for all FTP Operations.
	DialTimeout time.Duration // FTP connection timeout
}

// storageAdapter adapts FTP client to implement file.StorageProvider.
type storageAdapter struct {
	cfg  *Config

View on GitHub (pinned to 187eb24962)

Solutions

1. Confirm the prefix points to an existing, listable directory (StatObject first)
2. Check read permission on the directory for the FTP user
3. Fix passive-mode/firewall configuration so data connections succeed
4. Retry on transient network failures; inspect the wrapped error for the server reply

// confirm the prefix is an existing directory before listing
if _, err := fs.StatObject(ctx, prefix); err != nil { return err }

func isListError(err error) bool { return errors.Is(err, ftp.ErrFailedToListObjects) }

objs, err := fs.ListObjects(ctx, prefix)
if errors.Is(err, ftp.ErrFailedToListObjects) {
    // check perms/passive mode; retry or fail with context
    return fmt.Errorf("list %s: %w", prefix, err)
}

When it happens

Trigger: Calling ListObjects with a prefix whose directory cannot be listed: the path does not exist, permissions deny listing, or the data connection for the transfer fails.

Common situations: Listing a directory the FTP user cannot read; passive-mode blocked by firewall so the listing data connection never opens; path is a file, not a directory.

Related errors

• failed to create reader
• failed to list directory
• failed to dial FTP server %q: %w
• %w for %q: %w
• %w for %q at offset %d: %w

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