What causes "split path contains non-ASCII characters" in caddyserver/caddy?

Restore storage write access so cleanup can succeed.

ErrInvalidSplitPath

ErrInvalidSplitPath

Error message

split path contains non-ASCII characters

What it means

The stored config.bin loaded successfully but failed binary unmarshaling (echConfig.UnmarshalBinary — cryptobyte parsing of the ECHConfig wire structure), and the cleanup folder delete also failed. The config bytes are corrupt/truncated or in an incompatible format, and storage cannot be cleaned to free the ID.

Solutions

Restore storage write access so cleanup can succeed.
Manually delete the affected ech/configs/<id> folder and restart to regenerate the config.
When upgrading Caddy versions with ECH enabled, plan to reset ech/configs if old-format configs cause parse failures.
Ensure the storage backend writes atomically (or at least completes) to avoid truncated files.

Defensive patterns

Strategy: fallback

Try / catch

When binary unmarshal fails and cleanup succeeds, Caddy already self-heals (warns, frees the ID). Only when the delete also fails must you intervene: restore storage, remove the named folder, restart.

Prevention

Reset ech/configs across major Caddy upgrades to avoid stale binary formats.
Ensure storage atomicity to prevent truncated config.bin writes.
Keep cluster instances version-aligned.

When it happens

Trigger: cfg.UnmarshalBinary(echConfigBytes) errors (bad version, truncated HPKE public key, invalid length prefixes) AND storage.Delete of the folder errors (read-only/outage).

Common situations: Caddy version upgrades that changed the stored binary layout; storage corruption; interrupted writes leaving truncated config.bin; combined with a read-only or failing storage backend.

Related errors

AI-assisted analysis of caddyserver/caddy@50e54ee279 (2026-08-15). Data as JSON: /api/errors/596001b0e18e7feb. Report an issue: GitHub.

Appendix: source

Thrown at modules/caddyhttp/reverseproxy/fastcgi/fastcgi.go:39

	"net"
	"net/http"
	"path/filepath"
	"strconv"
	"strings"
	"time"
	"unicode/utf8"

	"go.uber.org/zap"
	"go.uber.org/zap/zapcore"

	"github.com/caddyserver/caddy/v2"
	"github.com/caddyserver/caddy/v2/modules/caddyhttp"
	"github.com/caddyserver/caddy/v2/modules/caddyhttp/reverseproxy"
	"github.com/caddyserver/caddy/v2/modules/caddytls"
)

var (
	ErrInvalidSplitPath = errors.New("split path contains non-ASCII characters")

	noopLogger = zap.NewNop()
)

func init() {
	caddy.RegisterModule(Transport{})
}

// Transport facilitates FastCGI communication.
type Transport struct {
	// Use this directory as the fastcgi root directory. Defaults to the root
	// directory of the parent virtual host.
	Root string `json:"root,omitempty"`

	// The path in the URL will be split into two, with the first piece ending
	// with the value of SplitPath. The first piece will be assumed as the
	// actual resource (CGI script) name, and the second piece will be set to
	// PATH_INFO for the CGI script to use.

View on GitHub (pinned to 50e54ee279)