What causes "number of providers must be greater than 0" in ipfs/kubo?

Set NumProviders to a positive integer (commonly 10-20) before calling FindProviders.

number of providers must be greater than 0

Error message

number of providers must be greater than 0

What it means

FindProviders validates settings.NumProviders before querying the routing system for provider records. A count below 1 would yield zero results from FindProvidersAsync, so the API rejects it explicitly as a programming/input error.

Source

Thrown at core/coreapi/routing.go:113

	settings, err := caopts.RoutingFindProvidersOptions(opts...)
	if err != nil {
		return nil, err
	}
	span.SetAttributes(attribute.Int("numproviders", settings.NumProviders))

	err = api.checkOnline(false)
	if err != nil {
		return nil, err
	}

	rp, _, err := api.core().ResolvePath(ctx, p)
	if err != nil {
		return nil, err
	}

	numProviders := settings.NumProviders
	if numProviders < 1 {
		return nil, errors.New("number of providers must be greater than 0")
	}

	pchan := api.routing.FindProvidersAsync(ctx, rp.RootCid(), numProviders)
	return pchan, nil
}

func (api *RoutingAPI) Provide(ctx context.Context, path path.Path, opts ...caopts.RoutingProvideOption) error {
	ctx, span := tracing.Span(ctx, "CoreAPI.DhtAPI", "Provide", trace.WithAttributes(attribute.String("path", path.String())))
	defer span.End()

	settings, err := caopts.RoutingProvideOptions(opts...)
	if err != nil {
		return err
	}
	span.SetAttributes(attribute.Bool("recursive", settings.Recursive))

	err = api.checkOnline(false)
	if err != nil {

View on GitHub (pinned to 329838acdf)

Solutions

Set NumProviders to a positive integer (commonly 10-20) before calling FindProviders.
If you want a sane default, use the options package default rather than a zero-valued struct.
Validate any user-supplied count and clamp it to >= 1 before calling the API.
Provide options.ProvideEditors/defaults from options.Name() helpers so fields are initialized.

Example fix

// before
opts := options.Routing.FindProviders() // NumProviders left 0
provs, err := api.Routing().FindProviders(ctx, p, opts)
// after
opts.NumProviders = 20
provs, err := api.Routing().FindProviders(ctx, p, opts)

Defensive patterns

Strategy: validation

Validate before calling

if settings.NumProviders < 1 {
	settings.NumProviders = 20 // or return a clear client-side error
}
provs, err := api.Routing().FindProviders(ctx, p, settings)

Try / catch

provs, err := api.Routing().FindProviders(ctx, p, settings)
if err != nil && strings.Contains(err.Error(), "number of providers") {
	settings.NumProviders = 20
	provs, err = api.Routing().FindProviders(ctx, p, settings)
}

Prevention

Initialize option structs via the options package constructors, not zero values
Clamp user-supplied counts to a sane minimum before calling
Document that NumProviders is required in wrapper APIs you expose

When it happens

Trigger: Calling Routing().FindProviders with NumProviders set to 0 or a negative value — typically because a limit/MaxResults variable was zero-valued, defaulted incorrectly, or parsed from user input without validation.

Common situations: Code that passes an unset integer field as the provider count, CLI wrappers mapping a --count flag defaulting to 0, and generic search helpers that reuse the same settings struct with the field unpopulated.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

AI-assisted analysis of ipfs/kubo@329838acdf (2026-09-03). Data as JSON: /api/errors/5fa80d6f63644ee5. Report an issue: GitHub.