Issue Review: cloudflare/workers-sdk#8722

Summary

Request to improve error message when conflicting configuration files (wrangler.toml and wrangler.json) exist.

Findings

• Created: 2025-03-30
• Updated: 2025-10-30
• Version: 4.6.0 → 4.60.0 (current)
• Component: Wrangler (config loading)
• Labels: bug, error-messaging
• Comments: 0

Key Evidence

1. No merged PRs reference issue #8722 or mention improving this specific error
2. Changelog search found no mention of this issue being addressed
3. Code review of packages/workers-utils/src/config/config-helpers.ts shows current behavior:
   • Config resolution uses findUpSync which returns the first match only
   • Search order: wrangler.json → wrangler.jsonc → wrangler.toml
   • If multiple config files exist, it silently uses one and does not error or warn
4. The error message in the issue screenshot ("conflicting configuration") likely comes from a different scenario - possibly when both a user config and deploy config exist at different paths (line 145 in config-helpers.ts)
5. The issue is a valid feature request to improve DX by warning users when multiple config formats exist

Analysis

The current implementation has a gap: when both wrangler.toml and wrangler.json exist in the same directory, wrangler silently prefers JSON without informing the user. This could lead to confusion if users expect their .toml file to be used. The reporter's request for better guidance is valid.

Recommendation

Status: KEEP OPEN

Reasoning: This is a valid UX improvement request that has not been addressed. The current behavior of silently preferring one config format over another when both exist can confuse users. The issue has the error-messaging label indicating it's tracked for error message improvements.

Action: Keep open for future enhancement. Consider implementing:

1. Warning when multiple config file formats exist in the same directory
2. Providing guidance on which file will be used and how to resolve the conflict

---

Solution Recommendation

Root Cause Analysis

File: packages/workers-utils/src/config/config-helpers.ts:59-86

export function findWranglerConfig(
  referencePath: string = process.cwd(),
  { useRedirectIfAvailable = false } = {}
): ConfigPaths {
  const userConfigPath =
    findUpSync(`wrangler.json`, { cwd: referencePath }) ??
    findUpSync(`wrangler.jsonc`, { cwd: referencePath }) ??
    findUpSync(`wrangler.toml`, { cwd: referencePath });
  // Never checks if multiple config files exist!
}

The code uses nullish coalescing (??) to select the first config file found but never warns if multiple exist. Priority order: wrangler.json > wrangler.jsonc > wrangler.toml.

Proposed Solution

Add detection and warning for multiple config files:

const CONFIG_FILE_NAMES = ["wrangler.json", "wrangler.jsonc", "wrangler.toml"] as const;

export function findWranglerConfig(
  referencePath: string = process.cwd(),
  { useRedirectIfAvailable = false, onWarning }: ResolveConfigPathOptions = {}
): ConfigPaths {
  // Find all existing config files
  const foundConfigs: { name: string; path: string }[] = [];
  
  for (const configName of CONFIG_FILE_NAMES) {
    const configPath = findUpSync(configName, { cwd: referencePath });
    if (configPath) {
      foundConfigs.push({ name: configName, path: configPath });
    }
  }

  // Check for multiple config files in the same directory
  if (foundConfigs.length > 1 && onWarning) {
    const sameDir = foundConfigs.filter(
      (c) => path.dirname(c.path) === path.dirname(foundConfigs[0].path)
    );
    
    if (sameDir.length > 1) {
      onWarning(dedent`
        Multiple configuration files found in the same directory:
          - Using: ${sameDir[0].name}
          - Ignoring: ${sameDir.slice(1).map(c => c.name).join(", ")}
        
        To resolve this conflict, either:
          1. Delete the configuration file(s) you don't want to use
          2. Use the --config flag to explicitly specify which file to use
        
        Priority order: wrangler.json > wrangler.jsonc > wrangler.toml
      `);
    }
  }

  const userConfigPath = foundConfigs[0]?.path;
  // ... rest of function
}

Then wire up the logger in packages/wrangler/src/config/index.ts:

const result = experimental_readRawConfig(args, {
  ...options,
  onWarning: (message) => logger.warn(message),
});

Implementation Difficulty: Easy

Factor	Assessment
Lines of code	~30-40 lines
Risk	Low - warning only, no behavior change
Testing	Easy - existing test patterns
Scope	2-3 files
Breaking changes	None

Files to Modify

1. packages/workers-utils/src/config/config-helpers.ts - Add multi-config detection
2. packages/wrangler/src/config/index.ts - Wire up warning callback
3. packages/workers-utils/tests/config/findWranglerConfig.test.ts - Add tests

Testing Recommendations

it("should warn when both wrangler.json and wrangler.toml exist", async () => {
    await seed({
        "wrangler.json": "{}",
        "wrangler.toml": "",
    });
    
    const warnings: string[] = [];
    findWranglerConfig(".", { onWarning: (msg) => warnings.push(msg) });
    
    expect(warnings).toHaveLength(1);
    expect(warnings[0]).toContain("Multiple configuration files found");
});