googleapis/mcp-toolbox · error

error converting config file: %s

Error message

error converting config file: %s

What it means

ParseConfig wraps any error from ConvertConfig with this message. ConvertConfig migrates legacy/nested config formats to the current flat format (YAML stream of docs); failure means the config file is structurally incompatible or malformed for migration, so parsing aborts. The inner error carries the doc index and offending key.

Source

Thrown at cmd/internal/config.go:199

		} else {
			column++
		}
	}
	return line, column
}

func (p *ConfigParser) ParseConfig(ctx context.Context, raw []byte) (Config, error) {
	var config Config
	// Replace environment variables if found
	output, err := p.parseEnv(string(raw))
	if err != nil {
		return config, fmt.Errorf("error parsing environment variables: %s", err)
	}
	raw = []byte(output)

	raw, err = ConvertConfig(ctx, raw)
	if err != nil {
		return config, fmt.Errorf("error converting config file: %s", err)
	}

	// Parse contents
	config.Sources, config.AuthServices, config.EmbeddingModels, config.Tools, config.Prompts, config.Groups, err = server.UnmarshalPrimitiveConfig(ctx, raw)
	if err != nil {
		return config, err
	}
	return config, nil
}

// ConvertConfig converts configuration file to flat format and rewrites toolsets
// to the group kind.
func ConvertConfig(ctx context.Context, raw []byte) ([]byte, error) {
	var buf bytes.Buffer
	// Manually copy top-level comments and empty lines from the source
	scanner := bufio.NewScanner(bytes.NewReader(raw))
	for scanner.Scan() {
		line := scanner.Text()

View on GitHub (pinned to 8cc6e09de2)

Solutions

1. Inspect the wrapped inner error ('doc %d: ... at key %q') and fix the structure at that key to the current format.
2. Run the migration command (toolbox migrate / runMigrate path) to convert the legacy config, then use the converted file.
3. Rewrite the config in the current flat format per current documentation examples.
4. Validate the YAML parses and all top-level keys (sources, tools, etc.) map string keys to proper maps.

Example fix

# before: nested legacy config
sources:
  my-pg:
    kind: postgres
    # ...
toolsets:
  default:
    toolsets: []
# after: run migration or write flat format
# toolbox migrate --in tools.yaml --out tools.flat.yaml
# tools.flat.yaml contains per-doc stream: sources, tools, ... in current schema

// smoke-test config load before deploy
cfg, err := parser.ParseConfig(ctx, raw)
if err != nil { log.Fatalf("config invalid: %v", err) }

if strings.Contains(err.Error(), "error converting config file") {
    // inner error gives doc index and key; fix or re-run toolbox migrate on the source file
    log.Fatalf("run `toolbox migrate` on the legacy config: %v", err)
}

When it happens

Trigger: Loading a config written in an older toolbox format (nested toolsets/kinds) that ConvertConfig cannot transform — e.g. a doc with non-string keys, or a key whose value is not the expected nested keys-and-type map.

Common situations: Upgrading from an old toolbox version whose YAML layout changed; hand-editing a config and breaking the expected structure; copying fragments between configs with mismatched formats.

Related errors

• environment variable not found: %s
• environment variables not found: - %s
• error parsing environment variables: %s
• doc %d: unexpected non-string key in input: %v
• doc %d: invalid config format at key %q: %w

AI-assisted analysis of googleapis/mcp-toolbox@8cc6e09de2 (2026-09-05). Data as JSON: /api/errors/d15c2d5bd79733a6. Report an issue: GitHub.