What causes "frp server address is required" in AlistGo/alist?

Fill in the FRP server address in the admin settings (the host of your frps server).

frp server address is required

Error message

frp server address is required

What it means

Returned by buildConfig in internal/frp/frp.go when the FRP client is being started but the frp server address setting (conf.FRPServerAddr) is empty. FRP (fast reverse proxy) needs a remote server to register the alist instance against; without an address no client config can be built.

Source

Thrown at internal/frp/frp.go:249

		if idx := bytes.IndexByte(buf, '\n'); idx >= 0 && idx+1 < len(buf) {
			buf = buf[idx+1:]
		}
	}
	text := strings.TrimRight(string(buf), "\n")
	if text == "" {
		return []string{}, nil
	}
	lines := strings.Split(text, "\n")
	if len(lines) <= limit {
		return lines, nil
	}
	return lines[len(lines)-limit:], nil
}

func buildConfig() (*v1.ClientCommonConfig, []v1.ProxyConfigurer, error) {
	serverAddr := setting.GetStr(conf.FRPServerAddr)
	if serverAddr == "" {
		return nil, nil, fmt.Errorf("frp server address is required")
	}

	serverPort := setting.GetInt(conf.FRPServerPort, 7000)
	authToken := setting.GetStr(conf.FRPAuthToken)
	proxyName := setting.GetStr(conf.FRPProxyName, "alist")
	proxyType := setting.GetStr(conf.FRPProxyType, "http")
	customDomain := setting.GetStr(conf.FRPCustomDomain)
	subdomain := setting.GetStr(conf.FRPSubdomain)
	remotePort := setting.GetInt(conf.FRPRemotePort, 0)
	localPort := setting.GetInt(conf.FRPLocalPort, 5244)
	tlsEnable := setting.GetBool(conf.FRPTLSEnable)
	stcpSecretKey := setting.GetStr(conf.FRPSTCPSecretKey)

	cfg := &v1.ClientCommonConfig{
		ServerAddr: serverAddr,
		ServerPort: serverPort,
		Auth: v1.AuthClientConfig{
			Method: v1.AuthMethodToken,

View on GitHub (pinned to 843d9dc814)

Solutions

Fill in the FRP server address in the admin settings (the host of your frps server).
Trim/validate the setting before starting the FRP client.
If FRP is not wanted, disable the FRP feature so buildConfig is not invoked.
Confirm the setting key persisted (check the settings storage) after saving.

Defensive patterns

Strategy: validation

Validate before calling

serverAddr := strings.TrimSpace(setting.GetStr(conf.FRPServerAddr))
if serverAddr == "" {
    // do not start FRP; prompt admin to configure it
}

Try / catch

cfg, proxies, err := buildConfig()
if err != nil {
    if strings.Contains(err.Error(), "frp server address is required") {
        // surface a settings-form error to the admin
    }
}

Prevention

Validate required FRP settings in the admin form before save (non-empty server address when FRP enabled).
Trim whitespace on the address field.
Keep FRP disabled until server address, and for tcp type remote_port, are set.

When it happens

Trigger: Enabling/starting the FRP client while the 'frp server addr' setting is unset or blank; loading settings from a fresh install where FRPServerAddr was never populated.

Common situations: User toggles FRP on in admin settings but forgets the server address field; settings migrated/restored without FRP keys; whitespace-only value stored.

Related errors

AI-assisted analysis of AlistGo/alist@843d9dc814 (2026-08-15). Data as JSON: /api/errors/9206b195823013d3. Report an issue: GitHub.