What causes "DHT timeout value must be >= 0" in ipfs/kubo?

Pass a non-negative duration, e.g. --dht-timeout=30s or --dht-timeout=0 for no wait

DHT timeout value must be >= 0

Error message

DHT timeout value must be >= 0

What it means

`ipfs ipns resolve --dht-timeout` rejects negative durations. When --dht-record / dht options are used, the parsed duration is validated to be non-negative because a negative DHT lookup timeout is meaningless. The value is later passed to namesys.ResolveWithDhtTimeout.

Source

Thrown at core/commands/name/ipns.go:119

		stream, _ := req.Options[streamOptionName].(bool)

		opts := []options.NameResolveOption{
			options.Name.Cache(!nocache),
		}

		if !recursive {
			opts = append(opts, options.Name.ResolveOption(namesys.ResolveWithDepth(1)))
		}
		if rcok {
			opts = append(opts, options.Name.ResolveOption(namesys.ResolveWithDhtRecordCount(rc)))
		}
		if dhttok {
			d, err := time.ParseDuration(dhtt)
			if err != nil {
				return err
			}
			if d < 0 {
				return errors.New("DHT timeout value must be >= 0")
			}
			opts = append(opts, options.Name.ResolveOption(namesys.ResolveWithDhtTimeout(d)))
		}

		if !stream {
			output, err := api.Name().Resolve(req.Context, name, opts...)
			if err != nil && (recursive || err != namesys.ErrResolveRecursion) {
				return err
			}

			pth, err := path.NewPath(output.String())
			if err != nil {
				return err
			}

			return cmds.EmitOnce(res, &ResolvedPath{pth.String()})
		}

View on GitHub (pinned to 329838acdf)

Solutions

Pass a non-negative duration, e.g. --dht-timeout=30s or --dht-timeout=0 for no wait
Fix the script that computes the duration so it clamps to >= 0

Example fix

// before
ipfs ipns resolve --dht-record --dht-timeout=-5s /ipns/example
// error: DHT timeout value must be >= 0
// after
ipfs ipns resolve --dht-record --dht-timeout=5s /ipns/example

Defensive patterns

Strategy: validation

Validate before calling

d, err := time.ParseDuration(flagValue)
if err != nil || d < 0 {
    return fmt.Errorf("dht-timeout must be a non-negative duration, got %q", flagValue)
}

Try / catch

if strings.Contains(err.Error(), "DHT timeout value must be >= 0") {
    // clamp the computed duration to 0 and retry
}

Prevention

Clamp computed durations: if d < 0 { d = 0 }
Avoid literal negative durations in scripts

When it happens

Trigger: Running `ipfs ipns resolve --dht-record --dht-timeout=-5s` or any negative duration string accepted by time.ParseDuration (e.g. '-1m').

Common situations: Scripted invocations computing the timeout from a difference that came out negative, or a typo placing the minus sign in the flag value.

Understand the failure class

Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

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