Vitest pool drops miniflare.unsafeDevRegistryPath

[matthew-gizmo]

Which Cloudflare product(s) does this pertain to?

Workers Vitest integration (@cloudflare/vitest-pool-workers)

Versions

• @cloudflare/vitest-pool-workers: 0.18.4
• wrangler: 4.110.0
• bundled miniflare: 4.20260708.1
• vitest: 4.1.8
• Node.js: 24.18.0

What is the problem?

cloudflareTest() accepts miniflare.unsafeDevRegistryPath, but the pool drops that option before constructing the project Miniflare instance. A service binding intended to resolve a separately running local Worker through Wrangler's dev registry therefore cannot resolve.

Minimal configuration shape:

cloudflareTest({
  remoteBindings: false,
  wrangler: {
    configPath: './wrangler.jsonc',
    environment: undefined
  },
  miniflare: {
    unsafeDevRegistryPath: registryPath,
    serviceBindings: {
      AI_SERVICE: 'ai'
    }
  }
});

With a local Worker named ai registered in registryPath, the test Worker fails to start:

Worker "core:user:vitest-pool-workers-runner-"'s binding "AI_SERVICE"
refers to a service "core:user:ai", but no such service is defined.

If the option is manually forwarded by the pool, Miniflare instead creates the dev-registry proxy and resolves the binding through the configured registry as expected.

Root cause

parseCustomPoolOptions() parses the Miniflare options, but buildProjectMiniflareOptions() builds a new object from SHARED_MINIFLARE_OPTIONS and selected pool fields. unsafeDevRegistryPath is not preserved or forwarded.

Proposed fix

Preserve options.miniflare.unsafeDevRegistryPath during custom option parsing and include it in the object returned by buildProjectMiniflareOptions(). The pool's internal WorkersPoolOptionsWithDefines type also needs to carry the option.

Conceptually:

const unsafeDevRegistryPath = options.miniflare.unsafeDevRegistryPath;
// ...
options.unsafeDevRegistryPath = unsafeDevRegistryPath;

return {
  ...SHARED_MINIFLARE_OPTIONS,
  ...(customOptions.unsafeDevRegistryPath === undefined
    ? {}
    : { unsafeDevRegistryPath: customOptions.unsafeDevRegistryPath }),
  // ...
};

I can prepare an upstream PR if this is an accepted supported use of the Vitest pool.

[workers-devprod]

Note

This is an automated, advisory triage report generated by workers-devprod. It is not an official maintainer response — a maintainer will follow up.

🤖 Automated triage report

Issue Triage: #14676

Summary

@cloudflare/vitest-pool-workers drops the miniflare.unsafeDevRegistryPath option before building the project Miniflare instance, so service bindings that should resolve a separately-running local Worker via Wrangler's dev registry fail to start — but a maintainer has clarified this is not a supported user-facing option.

Classification

• Type: Bug (effectively a feature request for a supported option)
• Component: packages/vitest-pool-workers
• Severity: Low
• Has Reproduction: Partial (minimal config shape + exact error, but no clonable repo)
• Quality: Complete

Findings

• Created: 2026-07-13T15:47:56Z
• Author: matthew-gizmo
• Version: @cloudflare/vitest-pool-workers 0.18.4, wrangler 4.110.0, miniflare 4.20260708.1, vitest 4.1.8, Node 24.18.0
• Labels: awaiting-response:reporter
• Comments: 2 (one automated triage report, one maintainer reply)

Analysis

• Maintainer has already responded and reframed the issue. In the most recent comment, maintainer emily-shen states that unsafeDevRegistryPath is not intended to be a user-facing option, and asks the reporter what they are actually trying to achieve. This supersedes the earlier automated "NEEDS VERIFICATION" triage note.
• A supported alternative exists. The maintainer points to the auxiliary workers pattern (fixtures/vitest-pool-workers-examples/multiple-workers/) for running/testing multiple workers in the same test environment, which is the intended path rather than reaching into the dev registry.
• This is not a straightforward code bug to fix. The "drop" of unsafeDevRegistryPath appears to be intentional — it is an internal/unsafe option, not part of the public pool surface. So the reporter's proposed fix (forwarding the option) is really a request to promote an internal option to a supported one, which is a product decision.
• The issue is now blocked on the reporter. The awaiting-response:reporter label is applied and the maintainer's clarifying question ("What are you trying to do?") is unanswered. Last activity 2026-07-14; the issue is brand new, so it is not stale.
• Report quality is high (full versions, exact error, root-cause hypothesis, proposed fix, offer to PR), so if the reporter's use case can't be met by auxiliary workers, this is a well-formed basis for a feature discussion.

Recommendation

Status: KEEP OPEN

Reasoning: A maintainer has stated unsafeDevRegistryPath is not a user-facing option and asked the reporter to describe their actual goal, pointing them at the supported auxiliary-workers pattern. The issue is now awaiting the reporter's response, so it should stay open (labeled awaiting-response:reporter) rather than be closed until we know whether the supported path meets their need.

Action: Wait for the reporter to answer the maintainer's clarifying question. If auxiliary workers solve their use case, close as answered/by-design. If not, convert to a feature request to evaluate whether dev-registry resolution should be a supported pool option. If the reporter does not respond within ~30 days, close as stale per the awaiting-response:reporter policy.

Suggested Labels: awaiting-response:reporter

Suggested Comment

Thanks for the detailed write-up. As Emily noted, unsafeDevRegistryPath is an internal option and isn't part of the supported @cloudflare/vitest-pool-workers surface, which is why the pool doesn't forward it. If your goal is to test against another local Worker, the supported approach is to declare it as an auxiliary worker — see the example here: https://github.com/cloudflare/workers-sdk/blob/main/fixtures/vitest-pool-workers-examples/multiple-workers/README.md. Could you let us know a bit more about what you're trying to do? If auxiliary workers don't cover your use case, we can look at whether resolving bindings through the dev registry should become a supported option.

Structured summary (JSON)

{
  "issueNumber": 14676,
  "title": "Vitest pool drops miniflare.unsafeDevRegistryPath",
  "githubUrl": "https://github.com/cloudflare/workers-sdk/issues/14676",
  "recommendation": "KEEP OPEN",
  "difficulty": "medium",
  "reasoning": "A maintainer clarified that unsafeDevRegistryPath is not a user-facing option and asked the reporter to describe their goal, pointing to the supported auxiliary-workers pattern. The issue is now awaiting the reporter's response.",
  "suggestedAction": "Wait for the reporter to answer the maintainer's clarifying question; if auxiliary workers solve their use case close as by-design, otherwise convert to a feature request. Close as stale if no response within ~30 days.",
  "hasSuggestedComment": true,
  "suggestedLabels": ["awaiting-response:reporter"]
}

[emily-shen]

This is not intended to be a user-facing option. What are you trying to do? If you'd like to test multiple workers, you can add auxiliary workers to run multiple workers in the test environment - see this example: https://github.com/cloudflare/workers-sdk/blob/main/fixtures/vitest-pool-workers-examples/multiple-workers/README.md