juanfont/headscale · error

%s starting tailscale DERPer container (version: %s): %w

Error message

%s starting tailscale DERPer container (version: %s): %w

What it means

Returned by the DERP integration-test helper when pool.BuildAndRunWithBuildOptions fails to build and start the tailscale DERPer container. It wraps the dockertest error with the intended container hostname and tailscale version for diagnosis.

Source

Thrown at integration/dsic/dsic.go:253

		})
	default:
		buildOptions.BuildArgs = append(buildOptions.BuildArgs, docker.BuildArg{
			Name:  "VERSION_BRANCH",
			Value: "v" + version,
		})
	}
	// Add integration test labels if running under hi tool
	dockertestutil.DockerAddIntegrationLabels(runOptions, "derp")

	container, err = pool.BuildAndRunWithBuildOptions(
		buildOptions,
		runOptions,
		dockertestutil.DockerRestartPolicy,
		dockertestutil.DockerAllowLocalIPv6,
		dockertestutil.DockerAllowNetworkAdministration,
	)
	if err != nil {
		return nil, fmt.Errorf(
			"%s starting tailscale DERPer container (version: %s): %w",
			hostname,
			version,
			err,
		)
	}

	log.Printf("Created %s container\n", hostname)

	dsic.container = container

	for i, cert := range dsic.caCerts {
		err = dsic.WriteFile(fmt.Sprintf("%s/user-%d.crt", caCertRoot, i), cert)
		if err != nil {
			return nil, fmt.Errorf("writing TLS certificate to container: %w", err)
		}
	}

View on GitHub (pinned to 565fd254d0)

Solutions

1. Verify Docker is reachable: docker ps works from the same user
2. Clean up leftovers from failed runs (docker network prune, hi cleanup / docker system prune)
3. Free disk/memory on the host and retry; check the build log for the failing Dockerfile step

// preflight before tests that start a DERPer
func dockerReachable() error {
    cli, err := client.NewClientWithOpts(client.FromEnv)
    if err != nil {
        return err
    }
    _, err = cli.Info(context.Background())
    return err
}

if err := dockerReachable(); err != nil {
    t.Skipf("docker unavailable: %v", err)
}

When it happens

Trigger: Running integration tests that spin up a DERPer while the Docker daemon is unreachable, the image build fails, or resource limits (disk, memory, network creation) prevent the container from starting.

Common situations: Docker daemon not running or the user lacking Docker permissions; CI runners with exhausted disk; pulling base images behind a restricted network; leftover networks/subnet exhaustion from prior failed runs.

Related errors

• creating certificates for derp test: %w
• writing TLS certificate to container: %w
• writing TLS key to container: %w
• DERPer is not ready: %w
• creating DERP server: %w

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