juanfont/headscale · error

path is a directory, only file is supported

Error message

path is a directory, only file is supported

What it means

Error "path is a directory, only file is supported" thrown in juanfont/headscale.

Source

Thrown at hscontrol/dns/extrarecords.go:20

import (
	"context"
	"crypto/sha256"
	"encoding/json"
	"errors"
	"fmt"
	"os"
	"sync"

	"github.com/cenkalti/backoff/v5"
	"github.com/fsnotify/fsnotify"
	"github.com/rs/zerolog/log"
	"tailscale.com/tailcfg"
	"tailscale.com/util/set"
)

// ErrPathIsDirectory is returned when a directory path is provided where a file is expected.
var ErrPathIsDirectory = errors.New("path is a directory, only file is supported")

type ExtraRecordsMan struct {
	mu      sync.RWMutex
	records set.Set[tailcfg.DNSRecord]
	watcher *fsnotify.Watcher
	path    string

	updateCh chan []tailcfg.DNSRecord
	closeCh  chan struct{}
	hash     [32]byte
}

// NewExtraRecordsManager creates a new [ExtraRecordsMan] and starts watching the file at the given path.
func NewExtraRecordsManager(path string) (*ExtraRecordsMan, error) {
	watcher, err := fsnotify.NewWatcher()
	if err != nil {
		return nil, fmt.Errorf("creating watcher: %w", err)
	}

View on GitHub (pinned to 565fd254d0)

Solutions

1. Inspect the wrapped error for the underlying cause and correct the failing condition (path is a directory, only file is supported); retry the operation after fixing the input, configuration, or environment.

Example fix

Inspect the wrapped error for the underlying cause and correct the failing condition (path is a directory, only file is supported); retry the operation after fixing the input, configuration, or environment.

When it happens

Trigger: Thrown at hscontrol/dns/extrarecords.go:20 when the library encounters an invalid state.

Common situations: dns.extra_records_path must point to a JSON file, not a directory. Pass the full file path in the headscale configuration.

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