[PR #5020] [CLOSED] Improve error messages for misplaced client-level configuration fields #5102

New issue

Closed

opened 2026-05-05 14:54:43 -06:00 by gitea-mirror · 0 comments

gitea-mirror commented

2026-05-05 14:54:43 -06:00

Owner

📋 Pull Request Information

Original PR: https://github.com/fatedier/frp/pull/5020
Author: @Copilot
Created: 10/15/2025
Status: ❌ Closed

Base: dev ← Head: copilot/fix-unmarshal-proxyconfig-error

📝 Commits (3)

9131d72 Initial plan
b9f909d Improve error messages for misplaced client-level config fields
d4eb63b Move clientLevelFields to common.go for shared access

📊 Changes

4 files changed (+156 additions, -2 deletions)

View changed files

📝 pkg/config/v1/common.go (+22 -0)
📝 pkg/config/v1/proxy.go (+28 -1)
📝 pkg/config/v1/proxy_test.go (+78 -0)
📝 pkg/config/v1/visitor.go (+28 -1)

📄 Description

Problem

Users were receiving cryptic error messages when accidentally placing client-level configuration fields inside proxy or visitor sections. For example, when trying to configure the VirtualNet feature as shown in the issue #4483:

[[proxies]]
name = "test-tcp"
type = "tcp"
localIP = "127.0.0.1"
localPort = 22
remotePort = 6000
featureGates = { VirtualNet = true }  # Wrong location
virtualNet.address = "100.86.0.2/24"  # Wrong location

The error message was unhelpful:

unmarshal ProxyConfig error: json: unknown field "featureGates"

This left users confused about what featureGates is, where it should be placed, and how to fix their configuration.

Solution

Enhanced the JSON unmarshaling error messages to detect when client-level configuration fields are mistakenly placed in proxy or visitor configurations and provide clear, actionable guidance.

Changes

Added clientLevelFields list in common.go - Maintains a centralized list of 16 common client-level fields (featureGates, virtualNet, auth, serverAddr, serverPort, log, webServer, transport, etc.)
Added enhanceProxyConfigError() function - Detects misplaced fields in proxy configurations and provides helpful error messages
Added enhanceVisitorConfigError() function - Detects misplaced fields in visitor configurations and provides helpful error messages
Added comprehensive unit tests - Tests cover multiple scenarios including featureGates, virtualNet, and auth field misplacement

Result

Now when users make the same mistake, they receive a clear, actionable error message:

unmarshal ProxyConfig error: json: unknown field "featureGates". 
Note: 'featureGates' is a client-level configuration field and should be placed 
at the root level of the config file, not within a [[proxies]] section. 
Please move it outside of the proxy configuration

The correct configuration should be:

serverAddr = "127.0.0.1"
serverPort = 7000

# Client-level fields at root level
featureGates = { VirtualNet = true }
virtualNet.address = "100.86.0.2/24"

[[proxies]]
name = "test-tcp"
type = "tcp"
localIP = "127.0.0.1"
localPort = 22
remotePort = 6000

Benefits

Better User Experience: Clear error messages guide users to correct configurations without needing to search documentation
Reduced Support Burden: Users can self-diagnose and fix common configuration mistakes
Comprehensive Coverage: Detects 16 commonly misplaced client-level fields
Maintainable: Centralized field list makes it easy to add more fields in the future
No Breaking Changes: Only enhances error messages, doesn't change any functionality

Testing

All existing tests continue to pass (no regression)
Added new unit tests specifically for the enhanced error messages
Manual testing confirms both incorrect configs show helpful errors and correct configs parse successfully

Fixes #4483

Original prompt

This section details on the original issue you should resolve

<issue_title>配置VirtualNet提示unmarshal ProxyConfig error: json: unknown field "featureGates"</issue_title>
<issue_description>### Bug Description

配置VirtualNet提示unmarshal ProxyConfig error: json: unknown field "featureGates"

frpc Version

v0.65.0

frps Version

v0.65.0

System Architecture

linux/amd64

Configurations

Client config:
serverAddr = "127.0.0.1"
serverPort = 7000

proxies
name = "test-tcp"
type = "tcp"
localIP = "127.0.0.1"
localPort = 22
remotePort = 6000

featureGates = { VirtualNet = true }
virtualNet.address = "100.86.0.2/24"
visitors
name = "vnet-visitor"
type = "stcp"
serverName = "vnet-server"
secretKey = "your-secret-key"
bindPort = -1
[visitors.plugin]
type = "virtual_net"
destinationIP = "100.86.0.1"

sudo ./frpc -c ./frpc.toml

unmarshal ProxyConfig error: json: unknown field "featureGates"

Logs

No response

Steps to reproduce

...

Affected area

Docs

Installation

Performance and Scalability

Security

User Experience

Test and Release

Developer Infrastructure

Client Plugin

Server Plugin

Extensions

Others</issue_description>

<agent_instructions>Try to debug what's the issue's problem</agent_instructions>

Comments on the Issue (you are @copilot in this section)

Fixes fatedier/frp#5019

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/fatedier/frp/pull/5020 **Author:** [@Copilot](https://github.com/apps/copilot-swe-agent) **Created:** 10/15/2025 **Status:** ❌ Closed **Base:** `dev` ← **Head:** `copilot/fix-unmarshal-proxyconfig-error` --- ### 📝 Commits (3) - [`9131d72`](https://github.com/fatedier/frp/commit/9131d726d5f5485bb37369c240b0e0b91ac9e56e) Initial plan - [`b9f909d`](https://github.com/fatedier/frp/commit/b9f909d9e785fb13f40e357485ff827f39de82b4) Improve error messages for misplaced client-level config fields - [`d4eb63b`](https://github.com/fatedier/frp/commit/d4eb63bb550db8f2da6a28e30b7d62c624375f6f) Move clientLevelFields to common.go for shared access ### 📊 Changes **4 files changed** (+156 additions, -2 deletions) <details> <summary>View changed files</summary> 📝 `pkg/config/v1/common.go` (+22 -0) 📝 `pkg/config/v1/proxy.go` (+28 -1) 📝 `pkg/config/v1/proxy_test.go` (+78 -0) 📝 `pkg/config/v1/visitor.go` (+28 -1) </details> ### 📄 Description ## Problem Users were receiving cryptic error messages when accidentally placing client-level configuration fields inside proxy or visitor sections. For example, when trying to configure the VirtualNet feature as shown in the issue #4483: ```toml [[proxies]] name = "test-tcp" type = "tcp" localIP = "127.0.0.1" localPort = 22 remotePort = 6000 featureGates = { VirtualNet = true } # Wrong location virtualNet.address = "100.86.0.2/24" # Wrong location ``` The error message was unhelpful: ``` unmarshal ProxyConfig error: json: unknown field "featureGates" ``` This left users confused about what `featureGates` is, where it should be placed, and how to fix their configuration. ## Solution Enhanced the JSON unmarshaling error messages to detect when client-level configuration fields are mistakenly placed in proxy or visitor configurations and provide clear, actionable guidance. ### Changes 1. **Added `clientLevelFields` list in `common.go`** - Maintains a centralized list of 16 common client-level fields (featureGates, virtualNet, auth, serverAddr, serverPort, log, webServer, transport, etc.) 2. **Added `enhanceProxyConfigError()` function** - Detects misplaced fields in proxy configurations and provides helpful error messages 3. **Added `enhanceVisitorConfigError()` function** - Detects misplaced fields in visitor configurations and provides helpful error messages 4. **Added comprehensive unit tests** - Tests cover multiple scenarios including featureGates, virtualNet, and auth field misplacement ### Result Now when users make the same mistake, they receive a clear, actionable error message: ``` unmarshal ProxyConfig error: json: unknown field "featureGates". Note: 'featureGates' is a client-level configuration field and should be placed at the root level of the config file, not within a [[proxies]] section. Please move it outside of the proxy configuration ``` The correct configuration should be: ```toml serverAddr = "127.0.0.1" serverPort = 7000 # Client-level fields at root level featureGates = { VirtualNet = true } virtualNet.address = "100.86.0.2/24" [[proxies]] name = "test-tcp" type = "tcp" localIP = "127.0.0.1" localPort = 22 remotePort = 6000 ``` ## Benefits - **Better User Experience**: Clear error messages guide users to correct configurations without needing to search documentation - **Reduced Support Burden**: Users can self-diagnose and fix common configuration mistakes - **Comprehensive Coverage**: Detects 16 commonly misplaced client-level fields - **Maintainable**: Centralized field list makes it easy to add more fields in the future - **No Breaking Changes**: Only enhances error messages, doesn't change any functionality ## Testing - All existing tests continue to pass (no regression) - Added new unit tests specifically for the enhanced error messages - Manual testing confirms both incorrect configs show helpful errors and correct configs parse successfully Fixes #4483  <details> <summary>Original prompt</summary> > > ---- > > *This section details on the original issue you should resolve* > > <issue_title>配置VirtualNet提示unmarshal ProxyConfig error: json: unknown field "featureGates"</issue_title> > <issue_description>### Bug Description > > 配置VirtualNet提示unmarshal ProxyConfig error: json: unknown field "featureGates" > > ### frpc Version > > v0.65.0 > > ### frps Version > > v0.65.0 > > ### System Architecture > > linux/amd64 > > ### Configurations > > Client config: > serverAddr = "127.0.0.1" > serverPort = 7000 > > [[proxies]] > name = "test-tcp" > type = "tcp" > localIP = "127.0.0.1" > localPort = 22 > remotePort = 6000 > > featureGates = { VirtualNet = true } > virtualNet.address = "100.86.0.2/24" > [[visitors]] > name = "vnet-visitor" > type = "stcp" > serverName = "vnet-server" > secretKey = "your-secret-key" > bindPort = -1 > [visitors.plugin] > type = "virtual_net" > destinationIP = "100.86.0.1" > > > # sudo ./frpc -c ./frpc.toml > unmarshal ProxyConfig error: json: unknown field "featureGates" > > ### Logs > > _No response_ > > ### Steps to reproduce > > 1. > 2. > 3. > ... > > > ### Affected area > > - [ ] Docs > - [ ] Installation > - [ ] Performance and Scalability > - [ ] Security > - [ ] User Experience > - [ ] Test and Release > - [ ] Developer Infrastructure > - [ ] Client Plugin > - [ ] Server Plugin > - [ ] Extensions > - [ ] Others</issue_description> > > <agent_instructions>Try to debug what's the issue's problem</agent_instructions> > > ## Comments on the Issue (you are @copilot in this section) > > <comments> > </comments> > </details> Fixes fatedier/frp#5019  --- 💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more [Copilot coding agent tips](https://gh.io/copilot-coding-agent-tips) in the docs. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>