juanfont/headscale · error

reaching DERP server: %w

Error message

reaching DERP server: %w

What it means

The DERP container was created but `WaitForRunning()` never observed it become healthy — the embedded health check (HTTP probe against the DERP port) kept failing until its timeout. Wraps the last probe error.

Source

Thrown at integration/scenario.go:1541

		err := user.syncWaitGroup.Wait()
		if err != nil {
			return err
		}
	}

	return nil
}

// CreateDERPServer creates a new DERP server in a container.
func (s *Scenario) CreateDERPServer(version string, opts ...dsic.Option) (*dsic.DERPServerInContainer, error) {
	derp, err := dsic.New(s.pool, version, s.Networks(), opts...)
	if err != nil {
		return nil, fmt.Errorf("creating DERP server: %w", err)
	}

	err = derp.WaitForRunning()
	if err != nil {
		return nil, fmt.Errorf("reaching DERP server: %w", err)
	}

	s.derpServers = append(s.derpServers, derp)

	return derp, nil
}

type scenarioOIDC struct {
	r   *dockertest.Resource
	cfg *types.OIDCConfig
}

func (o *scenarioOIDC) Issuer() string {
	if o.cfg == nil {
		panic("OIDC has not been created")
	}

	return o.cfg.Issuer

View on GitHub (pinned to 565fd254d0)

Solutions

1. Inspect the DERP container logs to see why it did not become healthy.
2. Verify the container is on the same Docker network(s) as the prober.
3. Fix any DERP config passed via dsic options (cert mode, port).
4. On slow runners, retry the scenario once after confirming the container eventually starts.

When it happens

Trigger: CreateDERPServer starts the container, then polls readiness; the DERP server crashes on startup (bad config, port bind failure) or is unreachable on the Docker network, so the wait times out.

Common situations: DERP server misconfiguration passed via opts; container exits immediately (check `docker logs`); Docker network segmentation preventing the probe from reaching the port; slow CI machine exceeding the fixed wait budget.

Related errors

• creating DERP server: %w
• %s failed to fetch tailscale status: %w
• checking local image availability: %w
• creating certificates for derp test: %w
• %s starting tailscale DERPer container (version: %s): %w

AI-assisted analysis of juanfont/headscale@565fd254d0 (2026-08-15). Data as JSON: /api/errors/f5b78facefccc0f6. Report an issue: GitHub.