fatedier/frp · error

invalid configuration file, not found [common] section

Error message

invalid configuration file, not found [common] section

What it means

Legacy INI-format client configuration loader (pkg/config/legacy). After parsing the .ini file it fetches the required 'common' section via f.GetSection('common'); if the section is absent, loading fails with this error. Every valid legacy frpc ini file must start with a [common] section holding the client-wide settings.

Source

Thrown at pkg/config/legacy/client.go:187

	PprofEnable bool `ini:"pprof_enable" json:"pprof_enable"`
}

// Supported sources including: string(file path), []byte, Reader interface.
func UnmarshalClientConfFromIni(source any) (ClientCommonConf, error) {
	f, err := ini.LoadSources(ini.LoadOptions{
		Insensitive:         false,
		InsensitiveSections: false,
		InsensitiveKeys:     false,
		IgnoreInlineComment: true,
		AllowBooleanKeys:    true,
	}, source)
	if err != nil {
		return ClientCommonConf{}, err
	}

	s, err := f.GetSection("common")
	if err != nil {
		return ClientCommonConf{}, fmt.Errorf("invalid configuration file, not found [common] section")
	}

	common := GetDefaultClientConf()
	err = s.MapTo(&common)
	if err != nil {
		return ClientCommonConf{}, err
	}

	common.Metas = GetMapWithoutPrefix(s.KeysHash(), "meta_")
	common.OidcAdditionalEndpointParams = GetMapWithoutPrefix(s.KeysHash(), "oidc_additional_")

	return common, nil
}

// if len(startProxy) is 0, start all
// otherwise just start proxies in startProxy map
func LoadAllProxyConfsFromIni(
	prefix string,

View on GitHub (pinned to 6c8a8d0a97)

Solutions

1. Add a [common] section header (exact lowercase) as the first section of the ini file
2. Move client-wide keys (server_addr, server_port, token/oidc settings) under it
3. If the file is actually TOML/YAML, load it through the current config loader instead of the legacy ini path
4. Prefer migrating to frpc.toml since the ini format is legacy

Example fix

; before
[ssh]
type = tcp
local_port = 22

; after
[common]
server_addr = "x.x.x.x"
server_port = 7000

[ssh]
type = tcp
local_port = 22

data, _ := os.ReadFile(path)
if !regexp.MustCompile(`(?m)^\[common\]`).Match(data) {
    return errors.New("legacy ini config must contain a [common] section")
}

When it happens

Trigger: Loading an ini config whose first section is a proxy (e.g. [ssh]) with no [common] header, a TOML/YAML file passed to the ini loader path, or a [Common]/[COMMON] variant — the ini.File here is loaded without case-insensitive sections (InsensitiveSections: false), so only the exact lowercase 'common' matches.

Common situations: Users migrating from very old frp versions whose examples omitted [common]; accidental deletion of the header during edits; case mismatch like [Common]; feeding the newer TOML-format frpc.toml into code paths that still call the legacy ini loader.

Related errors

• failed to render template for proxy %s: %v
• failed to parse proxy %s, err: %v
• failed to parse visitor %s, err: %v
• proxy %s role should be 'server' or 'visitor'
• local_port or remote_port is empty

AI-assisted analysis of fatedier/frp@6c8a8d0a97 (2026-08-15). Data as JSON: /api/errors/8df793a211a60f98. Report an issue: GitHub.