What causes "error retrieving configuration file: %w" in googleapis/mcp-toolbox?

Check the wrapped error text after 'error retrieving configuration file:' for the precise cause.

error retrieving configuration file: %w

Error message

error retrieving configuration file: %w

What it means

Raised by `toolbox migrate` when opts.GetCustomConfigFiles fails to resolve the configuration files to migrate (cmd/internal/migrate/command.go:61-66). The wrapped cause usually indicates the --configs/--prebuilt flags point at files or configs that cannot be loaded, parsed, or located.

Source

Thrown at cmd/internal/migrate/command.go:63

	return cmd.Command
}

func runMigrate(cmd *migrateCmd, opts *internal.ToolboxOptions) error {
	ctx, cancel := context.WithCancel(cmd.Context())
	defer cancel()

	ctx, shutdown, err := opts.Setup(ctx)
	if err != nil {
		return err
	}
	defer func() {
		_ = shutdown(ctx)
	}()

	logger := opts.Logger
	filePaths, _, err := opts.GetCustomConfigFiles(ctx)
	if err != nil {
		errMsg := fmt.Errorf("error retrieving configuration file: %w", err)
		logger.ErrorContext(ctx, errMsg.Error())
		return errMsg
	}

	logger.InfoContext(ctx, "migration process will start; any comments (except for top-level comments) presented in the original configuration files will not be preserved in the migrated files")
	var errs []error
	// process each files independently.
	for _, filePath := range filePaths {
		buf, err := os.ReadFile(filePath)
		if err != nil {
			errMsg := fmt.Errorf("unable to read tool file at %q: %w", filePath, err)
			logger.ErrorContext(ctx, errMsg.Error())
			errs = append(errs, errMsg)
			continue
		}
		newBuf, err := internal.ConvertConfig(ctx, buf)
		if err != nil {
			logger.ErrorContext(ctx, err.Error())

View on GitHub (pinned to 8cc6e09de2)

Solutions

Check the wrapped error text after 'error retrieving configuration file:' for the precise cause.
Verify the --configs file path(s) exist relative to the current working directory (or pass absolute paths).
Run `toolbox migrate --configs ./tools.yaml --dry-run` after confirming the file loads with `toolbox --configs ./tools.yaml` (server starts = config valid).
If using --prebuilt, confirm the kind name is valid (see docs/en/integrations prebuilt configs list).
Fix YAML syntax/schema errors so the config parses.

Example fix

// before
$ toolbox migrate --configs ./tooels.yaml
// error retrieving configuration file: open tooels.yaml: no such file or directory
// after
$ toolbox migrate --configs ./tools.yaml --dry-run

Defensive patterns

Strategy: validation

Validate before calling

// Verify config resolution before running migrate:
if _, err := os.Stat(cfgPath); err != nil {
    log.Fatalf("config path not accessible: %v", err)
}
// then sanity-load it:
cmd := exec.Command("toolbox", "--configs", cfgPath, "--help")
if err := cmd.Run(); err != nil {
    log.Fatalf("toolbox cannot load config: %v", err)
}

Try / catch

if err := runMigrate(); err != nil {
    if strings.Contains(err.Error(), "error retrieving configuration file") {
        // resolve config paths / prebuilt name, then retry
    }
    return err
}

Prevention

Always pass absolute paths to --configs or run from the config's directory.
Validate configs load with the server briefly before migrating.
Use --dry-run on migrate first to detect resolution issues without writing files.
Confirm --prebuilt kind names against the current toolbox version's supported list.

When it happens

Trigger: Running `toolbox migrate` with a --configs path that doesn't exist or isn't readable; malformed YAML that fails config parsing; invalid --prebuilt source name; errors fetching remote config sources.

Common situations: Typos in the config file path; running from a different working directory than expected; referencing a prebuilt config kind that doesn't exist; config file failing schema validation during load.

Understand the failure class

Background: "Config file not found": what it means and how to fix it in docker-sync, Maven, Vagrant, Turborepo and other tools — this error's family across 60 libraries.

Related errors

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