caddyserver/caddy · error

parsing environment file: %v

Error message

parsing environment file: %v

What it means

Thrown by loadEnvFromFile (cmd/main.go) when the --env-file passed to `caddy run`/`caddy start` cannot be parsed by parseEnvFile. It is a wrapper error: the underlying cause is one of the KEY=VALUE syntax violations detected while scanning the file line by line. The offending line number and reason are reported by the nested error.

Source

Thrown at cmd/main.go:361

// Duration returns the duration representation of the
// flag given by name. It returns false if the flag
// is not a duration type. It panics if the flag is
// not in the flag set.
func (f Flags) Duration(name string) time.Duration {
	val, _ := caddy.ParseDuration(f.String(name))
	return val
}

func loadEnvFromFile(envFile string) error {
	file, err := os.Open(envFile)
	if err != nil {
		return fmt.Errorf("reading environment file: %v", err)
	}
	defer file.Close()

	envMap, err := parseEnvFile(file)
	if err != nil {
		return fmt.Errorf("parsing environment file: %v", err)
	}

	for k, v := range envMap {
		// do not overwrite existing environment variables
		_, exists := os.LookupEnv(k)
		if !exists {
			if err := os.Setenv(k, v); err != nil {
				return fmt.Errorf("setting environment variables: %v", err)
			}
		}
	}

	// Update the storage paths to ensure they have the proper
	// value after loading a specified env file.
	caddy.ConfigAutosavePath = filepath.Join(caddy.AppConfigDir(), "autosave.json")
	caddy.DefaultStorage = &certmagic.FileStorage{Path: caddy.AppDataDir()}

	return nil

View on GitHub (pinned to 50e54ee279)

Solutions

1. Read the nested error: it names the exact line number and violation; open the env file at that line
2. Fix the line to strict KEY=VALUE form: no spaces in the key, no space directly after '=', quote values containing spaces or '#'
3. Prefix comment lines with '#' and delete blank/malformed lines
4. Validate the file before starting Caddy, e.g. `set -a; . ./env; set +a` in bash — if bash sources it cleanly, parseEnvFile usually will too
5. Re-run `caddy run --env-file ./env`

Example fix

# before (env file line 3)
DOMAIN=example.com
:9080
TOKEN = abc123

# after
DOMAIN=example.com
# :9080
TOKEN=abc123

# before starting Caddy, lint the env file the same way parseEnvFile does
line=0
while IFS= read -r l || [ -n "$l" ]; do
  line=$((line+1))
  t=$(printf '%s' "$l" | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')
  [ -z "$t" ] && continue
  case "$t" in \#*) continue;; esac
  case "$t" in *=*) ;; *) echo "line $line: missing '='"; exit 1;; esac
  k=${t%%=*}; k=${k#export }
  [ -z "$k" ] && { echo "line $line: empty key"; exit 1; }
  case "$k" in *[\ ]*) echo "line $line: space in key"; exit 1;; esac
done < env

When it happens

Trigger: Running `caddy run --env-file ./env` where the file contains a line with no '=' (error 222), an empty key (223), a key containing a space (224), or whitespace immediately after '=' (225). Empty lines and lines starting with '#' are skipped, so only real assignments can trigger it.

Common situations: Copying a shell script that uses `set VAR value` syntax, YAML-style `KEY: value`, or pasting a value containing an unquoted '#' comment; Windows files with keys containing trailing invisible characters; a multi-line quoted value whose closing quote is missing (parser keeps consuming lines).

Related errors

• can't parse line %d; line should be in KEY=VALUE format
• missing or empty key on line %d
• invalid key on line %d: contains whitespace: %s
• invalid value on line %d: whitespace before value: '%s'
• unmarshaling admin listener address from config: %v

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