[Web] Static WASM library: Actually selecting WebGpuExecutionProvider

[Andonvr]

Describe the issue

I successfully built the ONNXRuntime as a static library for WebAssembly (with pretty much this approach).

I log all available execution providers like so:

printf("ONNX Runtime version: %s\n", OrtGetApiBase()->GetVersionString());
auto providers = Ort::GetAvailableProviders();
printf("Available execution providers:\n");
for (const auto& provider : providers) {
    printf("  %s\n", provider.c_str());
}

And it correctly prints

ONNX Runtime version: 1.23.0
Available execution providers:
WebGpuExecutionProvider
CPUExecutionProvider

However, when running, it seems to be using the CPUExecutionProvider? I'm not actually sure, just speed-wise this seems to be the case.
So my questions are:

• How can I actually check which EP is used (not just which ones are available)
• How can I force it to use the WebGpuExecutionProvider, and raise an exception otherwise?

To reproduce

Urgency

Somewhat, my bachelors thesis would highly benefit from it lol

ONNX Runtime Installation

Built from Source

ONNX Runtime Version or Commit ID

ef60e38

Execution Provider

'webgpu' (WebGPU)

[edgchen1]

Only the CPU EP is enabled by default. Other EPs need to be added, e.g., with Ort::SessionOptions::AppendExecutionProvider() in the case of the WebGPU EP.

onnxruntime/include/onnxruntime/core/session/onnxruntime_cxx_api.h

Lines 1389 to 1390 in 776da26

	SessionOptionsImpl& AppendExecutionProvider(const std::string& provider_name,
	const std::unordered_map<std::string, std::string>& provider_options = {});

provider_name is "WebGPU" and available options are here (specified in AppendExecutionProvider() without the "ep.webgpuexecutionprovider." prefix:

onnxruntime/onnxruntime/core/providers/webgpu/webgpu_provider_options.h

Lines 10 to 33 in 776da26

	// The following are the options that can be set in the WebGPU provider options.
	constexpr const char* kPreferredLayout = "ep.webgpuexecutionprovider.preferredLayout";
	constexpr const char* kEnableGraphCapture = "ep.webgpuexecutionprovider.enableGraphCapture";
	constexpr const char* kDawnProcTable = "ep.webgpuexecutionprovider.dawnProcTable";
	constexpr const char* kDawnBackendType = "ep.webgpuexecutionprovider.dawnBackendType";
	constexpr const char* kDeviceId = "ep.webgpuexecutionprovider.deviceId";
	constexpr const char* kWebGpuInstance = "ep.webgpuexecutionprovider.webgpuInstance";
	constexpr const char* kWebGpuDevice = "ep.webgpuexecutionprovider.webgpuDevice";
	constexpr const char* kStorageBufferCacheMode = "ep.webgpuexecutionprovider.storageBufferCacheMode";
	constexpr const char* kUniformBufferCacheMode = "ep.webgpuexecutionprovider.uniformBufferCacheMode";
	constexpr const char* kQueryResolveBufferCacheMode = "ep.webgpuexecutionprovider.queryResolveBufferCacheMode";
	constexpr const char* kDefaultBufferCacheMode = "ep.webgpuexecutionprovider.defaultBufferCacheMode";
	constexpr const char* kValidationMode = "ep.webgpuexecutionprovider.validationMode";
	constexpr const char* kForceCpuNodeNames = "ep.webgpuexecutionprovider.forceCpuNodeNames";
	constexpr const char* kEnablePIXCapture = "ep.webgpuexecutionprovider.enablePIXCapture";
	constexpr const char* kPreserveDevice = "ep.webgpuexecutionprovider.preserveDevice";

[edgchen1]

How can I actually check which EP is used (not just which ones are available)

If you enable verbose logging, it will log what node is assigned to a particular EP.

How can I force it to use the WebGpuExecutionProvider, and raise an exception otherwise?

First, add the WebGPU EP to the session options. There is a session option configuration to disable CPU EP fallback:

onnxruntime/include/onnxruntime/core/session/onnxruntime_session_options_config_keys.h

Lines 267 to 280 in 776da26

	// Graph nodes that are not supported by the execution providers (EPs) explicitly added to the session are
	// assigned (i.e., "fallback") to the CPU EP by default.
	//
	// This option allows the user to disable the fallback of unsupported graph nodes to the CPU EP.
	// If this option is set to "1", session creation will fail if the execution providers other than the CPU EP cannot
	// fully support all of the nodes in the graph.
	//
	// It is invalid to set this option and explicitly add the CPU EP to the session. In this case, session creation
	// will also fail with an error.
	//
	// Option values:
	// - "0": CPU EP fallback is not disabled. [DEFAULT]
	// - "1": CPU EP fallback is disabled.
	static const char* const kOrtSessionOptionsDisableCPUEPFallback = "session.disable_cpu_ep_fallback";

It can be specified with Ort::SessionOptions::AddConfigEntry.

onnxruntime/include/onnxruntime/core/session/onnxruntime_cxx_api.h

Line 1366 in 776da26

SessionOptionsImpl& AddConfigEntry(const char* config_key, const char* config_value); ///< Wraps OrtApi::AddSessionConfigEntry

[Andonvr]

Woweee, thank you for the quick and especially thorough and detailed response! Can't wait to try it out first thing tomorrow! 🙏

[Andonvr]

I enabled verbose logging, and added the execution provider, without further options, so just:
m_session_options.AppendExecutionProvider("WebGPU");

But it fails to create the wgpu::Instance.

Here's the logs & error:

2025-09-05 09:54:13.516250 [W:onnxruntime:Default, cpuid_info.cc:91 LogEarlyWarning] Unknown CPU vendor. cpuinfo_vendor value: 0
2025-09-05 09:54:13.516875 [I:onnxruntime:Default, device_discovery_common.cc:34 operator()] Discovered OrtHardwareDevice {vendor_id:0x0, device_id:0x0, vendor:unknown, type:0, metadata: []}
2025-09-05 09:54:13.518695 [V:onnxruntime:Default, webgpu_provider_factory.cc:57 Create] WebGPU EP preferred layout: 1 (parsed from "")
2025-09-05 09:54:13.518910 [V:onnxruntime:Default, webgpu_provider_factory.cc:70 Create] WebGPU EP graph capture enable: 0
2025-09-05 09:54:13.519075 [V:onnxruntime:Default, webgpu_provider_factory.cc:89 Create] WebGPU EP force CPU node count: 0
2025-09-05 09:54:13.519200 [V:onnxruntime:Default, webgpu_provider_factory.cc:167 Create] WebGPU EP Device ID: 0
2025-09-05 09:54:13.519345 [V:onnxruntime:Default, webgpu_provider_factory.cc:168 Create] WebGPU EP WGPUInstance: 0
2025-09-05 09:54:13.519475 [V:onnxruntime:Default, webgpu_provider_factory.cc:169 Create] WebGPU EP WGPUDevice: 0
2025-09-05 09:54:13.519604 [V:onnxruntime:Default, webgpu_provider_factory.cc:170 Create] WebGPU EP DawnProcTable: 0
2025-09-05 09:54:13.519725 [V:onnxruntime:Default, webgpu_provider_factory.cc:171 Create] WebGPU EP ValidationMode: Basic
2025-09-05 09:54:13.519845 [V:onnxruntime:Default, webgpu_provider_factory.cc:172 Create] WebGPU EP PreserveDevice: 0
2025-09-05 09:54:13.519970 [V:onnxruntime:Default, webgpu_provider_factory.cc:198 Create] WebGPU EP Dawn backend type: 0
2025-09-05 09:54:13.520110 [V:onnxruntime:Default, webgpu_provider_factory.cc:225 Create] WebGPU EP storage buffer cache mode: Bucket
2025-09-05 09:54:13.520215 [V:onnxruntime:Default, webgpu_provider_factory.cc:229 Create] WebGPU EP uniform buffer cache mode: Simple
2025-09-05 09:54:13.520340 [V:onnxruntime:Default, webgpu_provider_factory.cc:232 Create] WebGPU EP query resolve buffer cache mode: Disabled
2025-09-05 09:54:13.520460 [V:onnxruntime:Default, webgpu_provider_factory.cc:235 Create] WebGPU EP default buffer cache mode: Disabled
2025-09-05 09:54:13.520570 [V:onnxruntime:Default, webgpu_provider_factory.cc:248 Create] WebGPU EP pix capture enable: 0
->> Uncaught onnxruntime::OnnxRuntimeException: /Users/anton/onnx-webgpu/onnxruntime/onnxruntime/core/providers/webgpu/webgpu_context.cc:890 auto onnxruntime::webgpu::WebGpuContextFactory::CreateContext(const WebGpuContextConfig &)::(anonymous class)::operator()() const default_instance_ != nullptr was false. Failed to create wgpu::Instance. <<-

And btw, this is how I build my project

set_target_properties(UsageExample PROPERTIES 
  LINK_FLAGS
    -O0
    -gsource-map 
    --js-library /Users/anton/my_project/src/onnx_webgpu/js-libs/library_webgpu_enum_tables.js 
    --js-library /Users/anton/my_project/src/onnx_webgpu/js-libs/library_webgpu_generated_struct_info.js 
    --js-library /Users/anton/my_project/src/onnx_webgpu/js-libs/library_webgpu_generated_sig_info.js 
    --js-library /Users/anton/my_project/src/onnx_webgpu/js-libs/library_webgpu.js 
    --bind 
    --no-entry 
    --emit-tsd=/Users/anton/my_project/demo/usage-example/public/UsageExample.d.ts 
    -pthread 
    -s AUDIO_WORKLET=1 
    -s WASM_WORKERS=32 
    -s PTHREAD_POOL_SIZE=32 
    -s ALLOW_MEMORY_GROWTH=1 
    -s ALLOW_TABLE_GROWTH=1 
    -s MALLOC=emmalloc 
    -s EXPORT_ES6=1 
    -s MODULARIZE=1 
    -s ENVIRONMENT=web,worker,shell 
    -s EXPORTED_FUNCTIONS='_module_init' 
    -s EXPORTED_RUNTIME_METHODS=['emscriptenRegisterAudioObject','emscriptenGetAudioObject','addFunction'] 
    -s NO_DISABLE_EXCEPTION_CATCHING 
    -s TOTAL_STACK=10MB 
  OUTPUT_NAME
    UsageExample 
  RUNTIME_OUTPUT_DIRECTORY
    /Users/anton/my_project/demo/usage-example/public
)

[edgchen1]

@fs-eire Would you mind taking a look?

[Andonvr]

Additional info:

• I'm on a MacBook Pro M3
• Removing -O0 -gsource-map doesn't fix it
• As you may be able to tell from the compile flags, I'm using this in an Audio Worklet / on the Web Audio Thread. But I also tried it with different flags running on a regular worker thread, which did not help (didn't expect it to tbh)

[vasanthzoh]

You might've tried the following already, but:

1. Could you try linking with -s ASYNCIFY?
2. Could you check if webgpu is enabled in your browser? https://developer.chrome.com/docs/web-platform/webgpu/troubleshooting-tips

[Andonvr]

WebGPU is definitely enabled :)
When using -s ASYNCIFY, it seems to solve the error! However, two more things now pop up:

• First, something that I suspect makes sense and I don't consider an error: ONNX Runtime still decides that my nodes should run on the CPU.
  Some nodes were not assigned to the preferred execution providers which may or may not have an negative impact on performance. e.g. ORT explicitly assigns shape related ops to CPU to improve perf.
  This maybe makes sense for my model, and I'm fine with it. I did not disable the CPU-fallback.
• But then this one actually looks like an error:
  Uncaught TypeError: Cannot read properties of undefined (reading 'pushErrorScope') at _wgpuDevicePushErrorScope (Benchmarks.js:1:135409)

I'm using Chrome Version 140.0.7339.133, which should have pushErrorScope