juanfont/headscale · error

creating DERP server: %w

Error message

creating DERP server: %w

What it means

`dsic.New` failed while creating the DERP-in-container server — dockertest could not build or run the DERP container image. The error wraps the underlying dockertest failure (image pull failure, build error, name/network conflict).

Source

Thrown at integration/scenario.go:1536

			user.syncWaitGroup.Go(func() error {
				return c.WaitForNeedsLogin(integrationutil.PeerSyncTimeout())
			})
		}

		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 {

View on GitHub (pinned to 565fd254d0)

Solutions

1. Read the wrapped dockertest error — pull/build failures name the image and reason.
2. Clean stale resources: `docker rm -f` leftover DERP containers or use the repo's cleanup command (`go run ./cmd/hi cleanup`).
3. Pre-pull the DERP image in CI before the test run.
4. Confirm the Docker daemon is up and disk space is available.

// Cheap pre-flight before creating the DERP server.
if _, err := pool.Client.Info(); err != nil {
    t.Fatalf("docker daemon unreachable: %v", err)
}

When it happens

Trigger: Calling `Scenario.CreateDERPServer(version, opts...)` when the DERP image cannot be pulled/built, the Docker daemon is unreachable, or a container with the generated name already exists.

Common situations: Offline/dev environment without the DERP image cached; Docker disk full; stale container from a previous crashed test run holding the network/name.

Related errors

• %s starting tailscale DERPer container (version: %s): %w
• reaching DERP server: %w
• creating certificates for derp test: %w
• writing TLS certificate to container: %w
• writing TLS key to container: %w

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