tls.certFile must be specified when tls is enabled

Error message

tls.certFile must be specified when tls is enabled

What it means

For the admin webServer, enabling TLS (webServer.tls present/non-nil) requires a server certificate. validateWebServerConfig returns immediately if tls.certFile is empty, so the dashboards' HTTPS listener cannot start half-configured.

Source

Thrown at pkg/config/v1/validation/common.go:27

// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

package validation

import (
	"fmt"
	"slices"

	v1 "github.com/fatedier/frp/pkg/config/v1"
)

func validateWebServerConfig(c *v1.WebServerConfig) error {
	if c.TLS != nil {
		if c.TLS.CertFile == "" {
			return fmt.Errorf("tls.certFile must be specified when tls is enabled")
		}
		if c.TLS.KeyFile == "" {
			return fmt.Errorf("tls.keyFile must be specified when tls is enabled")
		}
	}

	return ValidatePort(c.Port, "webServer.port")
}

// ValidatePort checks that the network port is in range
func ValidatePort(port int, fieldPath string) error {
	if 0 <= port && port <= 65535 {
		return nil
	}
	return fmt.Errorf("%s: port number %d must be in the range 0..65535", fieldPath, port)
}

func validateLogConfig(c *v1.LogConfig) error {

View on GitHub (pinned to 6c8a8d0a97)

Solutions

Set webServer.tls.certFile to a valid PEM certificate path (alongside keyFile)
Or remove the webServer.tls section entirely if HTTPS on the admin endpoint is not wanted (empty tls:{} still counts as enabled)
Verify file permissions so frp can read the cert at startup

Example fix

# before
[webServer]
port = 7400
[webServer.tls]
keyFile = "admin.key"

# after
[webServer]
port = 7400
[webServer.tls]
certFile = "admin.crt"
keyFile = "admin.key"

Defensive patterns

Strategy: validation

Validate before calling

func webServerTLSComplete(c *v1.WebServerConfig) bool {
    return c.TLS == nil || c.TLS.CertFile != ""
}

Prevention

Avoid empty tls:{} maps in YAML — they enable the TLS requirement
Pair cert and key paths in one template variable set

When it happens

Trigger: Client or server config with [webServer.tls] section (or tls: {} in YAML) but no certFile key — e.g. only keyFile provided, or the tls block added as a placeholder.

Common situations: Copying a webServer block and forgetting the cert path; intending plain HTTP but accidentally leaving an empty tls map which YAML parses as non-nil; cert path variable left blank in a template.

Understand the failure class

SSL/TLS and certificate errors — how TLS handshakes and certificate validation fail.

Related errors

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