What causes "fatal error unmarshal config: %w" in flipped-aurora/gin-vue-admin?

Compare your config.yaml against the latest config.yaml example shipped with the server version and fix mismatched types/structure

flipped-aurora/gin-vue-admin · critical

fatal error unmarshal config: %w

Error message

fatal error unmarshal config: %w

What it means

After viper successfully reads the config file, Viper() unmarshals it into global.GVA_CONFIG. If the mapping fails (struct field type mismatch with YAML value types), it panics with this error since a partially-loaded config is unsafe.

Source

Thrown at server/core/viper.go:36

	config := getConfigPath()

	v := viper.New()
	v.SetConfigFile(config)
	v.SetConfigType("yaml")
	err := v.ReadInConfig()
	if err != nil {
		panic(fmt.Errorf("fatal error config file: %w", err))
	}
	v.WatchConfig()

	v.OnConfigChange(func(e fsnotify.Event) {
		fmt.Println("config file changed:", e.Name)
		if err = v.Unmarshal(&global.GVA_CONFIG); err != nil {
			fmt.Println(err)
		}
	})
	if err = v.Unmarshal(&global.GVA_CONFIG); err != nil {
		panic(fmt.Errorf("fatal error unmarshal config: %w", err))
	}

	// root 适配性 根据root位置去找到对应迁移位置,保证root路径有效
	global.GVA_CONFIG.AutoCode.Root, _ = filepath.Abs("..")
	return v
}

// getConfigPath 获取配置文件路径, 优先级: 命令行 > 环境变量 > 默认值
func getConfigPath() (config string) {
	// `-c` flag parse
	flag.StringVar(&config, "c", "", "choose config file.")
	flag.Parse()
	if config != "" { // 命令行参数不为空 将值赋值于config
		fmt.Printf("您正在使用命令行的 '-c' 参数传递的值, config 的路径为 %s\n", config)
		return
	}
	if env := os.Getenv(internal.ConfigEnv); env != "" { // 判断环境变量 GVA_CONFIG
		config = env

View on GitHub (pinned to 3136500ef3)

Solutions

Compare your config.yaml against the latest config.yaml example shipped with the server version and fix mismatched types/structure
Check the wrapped unmarshal error for the exact field path and expected type
Add any newly introduced config sections required by the upgraded version
Re-merge custom settings into a fresh example config rather than patching the old one

Example fix

// before
system:
  port: "8888"
  addr-mismatch: true   # unknown/misspelled key or wrong type
// after
system:
  port: 8888
  addr: 8888            # match current struct field names/types

Defensive patterns

Strategy: validation

Validate before calling

var probe map[string]interface{}
if err := yaml.Unmarshal(content, &probe); err != nil {
    log.Fatalf("YAML syntax invalid: %v", err)
}
// then diff keys/types against the current example config

Prevention

Diff your config against the version-matched example after every upgrade
Keep numeric fields unquoted and nested maps at correct indent levels
Test config loading in CI with the real struct before deploying

When it happens

Trigger: Config file parses as YAML but a value cannot be decoded into the corresponding field of config.Server/GlobalConfig, e.g. a string where an int is expected, or wrong nesting level of a map key.

Common situations: Upgrading gva to a version with a changed config struct while keeping an old config.yaml; hand-editing and mistyping a value type (port as "8080" with quotes may still decode, but nested maps misplaced won't); adding keys at the wrong indent level.

Related errors

AI-assisted analysis of flipped-aurora/gin-vue-admin@3136500ef3 (2026-08-31). Data as JSON: /api/errors/29d4235f070c39da. Report an issue: GitHub.