What causes "error parsing include file '%s', %v" in nats-io/nats-server?

Parse the included file standalone (the %v suffix holds the root cause) and fix the inner error first.

error parsing include file '%s', %v

Error message

error parsing include file '%s', %v

What it means

An include item caused the parser to recursively parse the referenced file (ParseFile, or ParseFileWithChecks in pedantic mode) at filepath.Join(p.fp, it.val); that inner parse returned an error, which is wrapped and re-reported with the include file's name.

Source

Thrown at conf/parse.go:419

			default:
				// Special case to add position context to bcrypt references.
				p.setValue(&token{it, value, false, fp})
			}
		} else {
			p.setValue(value)
		}
	case itemInclude:
		var (
			m   map[string]any
			err error
		)
		if p.pedantic {
			m, err = ParseFileWithChecks(filepath.Join(p.fp, it.val))
		} else {
			m, err = ParseFile(filepath.Join(p.fp, it.val))
		}
		if err != nil {
			return fmt.Errorf("error parsing include file '%s', %v", it.val, err)
		}
		for k, v := range m {
			p.pushKey(k)

			if p.pedantic {
				switch tk := v.(type) {
				case *token:
					p.pushItemKey(tk.item)
				}
			}
			p.setValue(v)
		}
	}

	return nil
}

// Used to map an environment value into a temporary map to pass to secondary Parse call.

View on GitHub (pinned to 3a66a489d2)

Solutions

Parse the included file standalone (the %v suffix holds the root cause) and fix the inner error first.
Verify the include path resolves correctly relative to the parent config's directory (p.fp).
Ensure the file exists and is readable with the expected format.
Check for circular includes or accidentally including a non-config file.

Example fix

// before (parent.conf)
include = common/confg.conf   # typo
// after
include = common/conf.conf

Defensive patterns

Strategy: try-catch

Validate before calling

if _, err := os.Stat(includePath); err != nil {
	return fmt.Errorf("include %q unreadable: %w", includePath, err)
}
if err := conf.ParseFile(includePath); err != nil {
	return fmt.Errorf("include %q invalid: %w", includePath, err)
}

Try / catch

if err := parseConfig(); err != nil {
	var ierr error
	if _, gerr := fmt.Sscanf(err.Error(), "error parsing include file %q, %v", new(string), &ierr); gerr == nil && ierr != nil {
		return fmt.Errorf("bad include: %w", ierr)
	}
	return err
}

Prevention

Validate each include file in CI independently.
Use paths relative to the parent config's directory and test them.
Avoid circular includes; keep an include dependency graph.
After editing an included file, re-run the full config parse before deploy.

When it happens

Trigger: processItem (from parse) hits the include case and the included file has any parse error — bad syntax, out-of-range floats, unknown variable references, wrong types — or the path resolves to an unreadable/invalid file.

Common situations: Included config was edited and broke, include path typo resolving to the wrong file, relative path assumptions differing from p.fp, or recursive includes producing failures.

Related errors

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