juanfont/headscale · error

directory is required

Error message

directory is required

What it means

Wrapped error from doLoginURLWithClient when io.ReadAll on the login response body fails. The request itself succeeded (resp is non-nil and is closed via defer), but streaming the body errored — typically a dropped connection mid-body.

Source

Thrown at cmd/mapresponses/main.go:21

import (
	"encoding/json"
	"errors"
	"fmt"
	"os"

	"github.com/creachadair/command"
	"github.com/creachadair/flax"
	"github.com/juanfont/headscale/hscontrol/mapper"
	"github.com/juanfont/headscale/integration/integrationutil"
)

type MapConfig struct {
	Directory string `flag:"directory,Directory to read map responses from"`
}

var (
	mapConfig            MapConfig
	errDirectoryRequired = errors.New("directory is required")
)

func main() {
	root := command.C{
		Name: "mapresponses",
		Help: "MapResponses is a tool to map and compare map responses from a directory",
		Commands: []*command.C{
			{
				Name:     "online",
				Help:     "",
				Usage:    "run [test-pattern] [flags]",
				SetFlags: command.Flags(flax.MustBind, &mapConfig),
				Run:      runOnline,
			},
			command.HelpCommand(nil),
		},
	}

View on GitHub (pinned to 565fd254d0)

Solutions

1. Re-run — this is almost always a transient transport failure.
2. If persistent, capture headscale/provider logs at the timestamp to see if the handler crashed mid-response.
3. Check for proxies between the test and containers adding body-size or idle limits.

if err != nil && strings.Contains(err.Error(), "reading response body") {
    // transient transport drop: retry the whole login GET once
}

When it happens

Trigger: The control server or OIDC provider closes the connection while the response body is being read; keep-alive race, proxy or Docker network interruption, or a very large body hitting a read deadline.

Common situations: Flaky Docker networking in CI, headscale restarting mid-response, reverse proxy timeouts when the login handler is slow.

Related errors

• test pattern is required as first argument or use --test fla
• %s sending confirm request: %w
• %s reading confirm response: %w
• health check timed out
• unexpected end of container wait

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