What causes "no relay server available" in netbirdio/netbird?

Configure a relay service URL in the management settings

no relay server available

Error message

no relay server available

What it means

pickErr merges per-server connection failures and returns this error only when there are no failures to merge — the candidate relay URL list was empty, so no relay was ever tried. It is distinct from relays that were attempted and failed: here the picker had nothing to pick from.

Source

Thrown at shared/relay/client/picker.go:116

			if err := cr.RelayClient.Close(); err != nil {
				log.Errorf("failed to close connection to %s: %v", cr.Url, err)
			}
			continue
		}

		hasSuccess = true
		successChan <- cr
	}
	if !hasSuccess {
		errChan <- pickErr(errs)
	}
	close(successChan)
}

// pickErr combines per-server connection failures into a single error.
func pickErr(errs []error) error {
	if len(errs) == 0 {
		return errors.New("no relay server available")
	}
	return errors.Join(errs...)
}

View on GitHub (pinned to 93e97f4bf1)

Solutions

Configure a relay service URL in the management settings
Verify the network map actually delivers relay addresses to the agent
For self-hosted, deploy a relay and register it with management

Defensive patterns

Strategy: fallback

Validate before calling

relayURLs := networkMap.RelayURLs()
if len(relayURLs) == 0 {
	return fmt.Errorf("network map contains no relay address; check management relay configuration")
}

Try / catch

conn, err := picker.Pick(ctx)
if err != nil {
	if err.Error() == "no relay server available" {
		// nothing was configured: fall back to a default relay URL or degrade to direct connections
	}
	return nil, err
}

Prevention

Validate the relay configuration on management at deploy time
Distinguish empty-candidate from all-candidates-failed in logs
For self-hosted, health-check the relay registration after setup

When it happens

Trigger: Management delivered no relay address in the network map, or the relay client was constructed with an empty list of relay URLs.

Common situations: Self-hosted management deployed without configuring a relay; relay URL misparsed from config; a management version that does not populate the relay field for this client.

Related errors

AI-assisted analysis of netbirdio/netbird@93e97f4bf1 (2026-08-16). Data as JSON: /api/errors/206578eb3b4f5a08. Report an issue: GitHub.