variable reference for '%s' on line %d could not be parsed:

Error message

variable reference for '%s' on line %d could not be parsed: %s

What it means

A variable reference item was resolved via p.lookupVariable, which returned a non-nil error, meaning the reference string itself could not be parsed (e.g. malformed ${...} reference). The underlying parse error is included in the message.

Source

Thrown at conf/parse.go:386

	case itemDatetime:
		dt, err := time.Parse("2006-01-02T15:04:05Z", it.val)
		if err != nil {
			return fmt.Errorf(
				"expected Zulu formatted DateTime, but got '%s'", it.val)
		}
		setValue(it, dt)
	case itemArrayStart:
		var array = make([]any, 0)
		p.pushContext(array)
	case itemArrayEnd:
		array := p.ctx
		p.popContext()
		setValue(it, array)
	case itemVariable:
		value, found, err := p.lookupVariable(it.val)
		if err != nil {
			return fmt.Errorf("variable reference for '%s' on line %d could not be parsed: %s",
				it.val, it.line, err)
		}
		if !found {
			return fmt.Errorf("variable reference for '%s' on line %d can not be found",
				it.val, it.line)
		}

		if p.pedantic {
			switch tk := value.(type) {
			case *token:
				// Mark the looked up variable as used, and make
				// the variable reference become handled as a token.
				tk.usedVariable = true
				p.setValue(&token{it, tk.Value(), false, fp})
			default:
				// Special case to add position context to bcrypt references.
				p.setValue(&token{it, value, false, fp})
			}

View on GitHub (pinned to 3a66a489d2)

Solutions

Fix the variable reference syntax in the config to match the expected form (e.g. ${VAR} with a valid name).
Read the wrapped error in the message ('...: %s') to identify the exact parse problem.
Remove empty or malformed references and set the value literally.
Check for shell expansion mangling the reference before the config file was written.

Example fix

// before
endpoint = ${}
// after
endpoint = ${API_ENDPOINT}

Defensive patterns

Strategy: validation

Validate before calling

refRe := regexp.MustCompile(`^\$\{[A-Za-z_][A-Za-z0-9_]*\}$`)
if !refRe.MatchString(ref) {
	return fmt.Errorf("malformed variable reference %q", ref)
}

Prevention

Use ${NAME} with a valid identifier; avoid empty references.
Beware of shell interpolation rewriting references when generating configs.
Grep generated configs for suspicious '${}' or '$' patterns.

When it happens

Trigger: processItem (from parse) hits case itemVariable with a malformed reference in it.val (empty name, bad characters, nested/unclosed syntax), causing lookupVariable to return err.

Common situations: Typos in variable interpolation syntax, empty ${} references, references copied from shell with unsupported syntax ($VAR without braces if braces are required), or accidentally escaped/duplicated braces.

Related errors

AI-assisted analysis of nats-io/nats-server@3a66a489d2 (2026-09-02). Data as JSON: /api/errors/c1de19126d001c8e. Report an issue: GitHub.