MetaMask 連線失敗：如何排查 SSE 故障而不過早下結論

A browser-extension error, a successful retry, and a convincing explanation that the evidence had not earned

It looked like a useful clue.

A streaming application was searching for export customers across multiple sources. During troubleshooting, the browser console showed a MetaMask connection error. After MetaMask was disabled, the interface populated its example fields, started the search, entered the first of eight stages, and displayed 17 initial results in roughly five seconds.

The tempting conclusion was immediate:

MetaMask intercepts fetch, terminates long-running SSE connections, and causes the application to fail.

That explanation was specific. It sounded technically plausible. It also went beyond the available evidence.

The successful retry established that the application could start returning results in one run without the extension. It did not establish that the extension had intercepted the request, imposed a timeout, or caused the earlier failure.

This article develops a debugging workflow from that distinction. It is not a confirmed MetaMask root-cause report. The initial observation is real; the experiments and architecture below are a proposed way to investigate it.

The central principle is attribution: an error can be genuine without being the cause of the failure you are investigating.

1. Start With an Evidence Ledger, Not a Root-Cause Story

Before changing code, separate observations from interpretations.

This table prevents a subtle escalation:

Something changed.
    ↓
The application behaved differently.
    ↓
The changed component must explain everything.

The extension state is a useful experimental variable. It is not yet a complete explanation.

There is independent evidence that this error family can appear in applications unrelated to cryptocurrency. TrackJS documents Failed to connect to MetaMask as an extension-origin error that can occur independently of a site’s own functionality. That supports treating it as a possible source of noise—not automatically dismissing every nearby failure. trackjs

2. Separate Three Contracts That Can Fail Independently

For this investigation, I would model the application as three contracts.

The transport contract

Can the browser receive the stream?

Relevant evidence includes:

• Response headers received.
• First event received.
• Last event received.
• Sequence gaps.
• An explicit completion event.
• A transport or stream-reading error.

The execution contract

Does the search actually run and finish?

Relevant evidence includes:

• Job creation.
• Worker progress.
• Dependency failures.
• Persisted results.
• Final job state.

The telemetry contract

Does the recorded exception belong to the application?

Relevant evidence includes:

• Extension-origin versus application-origin frames.
• The original rejection payload.
• Breadcrumbs.
• A corresponding failed user operation.

These contracts should not be collapsed into a single “working” or “broken” flag.

A worker may finish while the browser loses its connection. The browser may remain connected while a dependency stalls. An extension may generate an exception while the application continues normally.

For this application, I would therefore make each contract observable separately.

3. Remove the Search Engine From the First Experiment

Testing only the full customer-search workflow introduces too many moving parts:

Browser
  → application client
  → deployment path
  → search service
  → external sources
  → result processing
  → streamed response

My first diagnostic tool would be a deterministic stream endpoint passing through the same deployment path but performing no external searches.

A proposed test interface:

GET /debug/stream?mode=active
GET /debug/stream?mode=silent
GET /debug/stream?mode=disconnect
GET /debug/stream?mode=invalid-payload

Each mode should test a different condition:

These are proposed fault-injection modes, not results from an executed experiment.

Active streams and silent streams are different tests

A stream emitting data every two seconds does not adequately test an inactivity hypothesis.

Test both:

1. A continuously active stream.
2. A stream with controlled silent intervals.
3. The same silent intervals with periodic heartbeat comments.

MDN documents SSE comments as a possible keep-alive mechanism for preventing some connection timeouts. Comments begin with : and are ignored by the event parser. This makes them useful for transport maintenance, but not equivalent to application-visible progress events. developer.mozilla

For example:

: keep-alive

An application-visible heartbeat is a different design choice:

event: heartbeat
data: {"serverTime":"2026-10-28T08:00:00Z"}

In the proposed diagnostic client, I would track transport activity and application progress separately rather than letting a heartbeat imply that the search is advancing.

4. Run a Controlled Comparison

Start with a small matrix:

Repeat each condition and vary the order. Keep the browser version, application version, input, and deployment configuration fixed.

Avoid treating “normal profile versus incognito” as a perfectly isolated extension test. That comparison may change more than extension availability. For this investigation, record the environment explicitly and minimize differences between conditions.

The results should guide the next experiment:

• If only extension-enabled runs fail, the extension hypothesis becomes stronger.
• If only real searches fail, investigate search dependencies and application logic.
• If silent streams fail in both environments, investigate inactivity-related behavior.
• If the server completes while the client reports failure, focus on delivery and client handling.
• If nothing fails reproducibly, report that limitation rather than manufacturing certainty.

These patterns narrow the investigation. They do not replace inspecting the actual failure.

5. Measure Two Clocks

For every disconnect, record both:

elapsed_since_request_start
elapsed_since_last_received_data

These measurements answer different questions.

A failure consistently associated with total connection age suggests a different experiment from one associated with a long quiet period.

Do not immediately label either pattern a timeout imposed by a specific component. First determine whether the pattern exists.

My proposed run record would include:

{
  "runId": "run-042",
  "jobId": "job-109",
  "extensionState": "enabled",
  "headersReceivedAt": null,
  "firstEventAt": null,
  "lastEventAt": null,
  "lastSequence": null,
  "completionReceived": false,
  "abortReason": null,
  "clientError": null,
  "serverJobState": null
}

This is an instrumentation schema, not a sample experimental result.

The useful question is not merely “Did fetch fail?” It is:

At which boundary did the observed behavior diverge from the expected behavior?

6. A Real Example: Filtering Wallet Noise Without Claiming to Fix Transport

A public change in the Suna repository illustrates a related but narrower engineering problem.

The commit describes an unhandled rejection carrying a plain object:

{
  code: 4900,
  message: "The provider is disconnected from all chains."
}

According to the commit description, the rejection lacked a useful stack, was captured by Sentry as a synthetic unhandled rejection, and appeared alongside a MetaMask connection breadcrumb. The maintainers classified that specific event as injected wallet-provider noise in their application. github

The important lesson is how narrowly they approached the fix:

• Match a specific rejection shape.
• Preserve events containing application-owned frames.
• Filter at the telemetry boundary.
• Add tests for both events that should be dropped and similar events that should remain. github

That is a telemetry correction.

It is not evidence that the extension intercepted generic HTTP requests. It is not an SSE repair.

TrackJS also discusses filtering this error family, but its example uses broader message matching. Comparing these approaches raises a useful review question: could the filter suppress an application error merely because its message mentions a wallet? trackjs

For my application, I would require negative tests before introducing any filter:

Known extension-noise signature → eligible for filtering
Similar application error      → retained
Event with first-party frames   → retained
Unknown rejection               → retained

Cleaning the dashboard should never become a substitute for understanding failed operations.

7. Make the Search Survive the Connection

Regardless of the final root cause, I would change one architectural assumption:

The browser connection should observe the search, not own its lifetime.

A proposed API:

POST /search-jobs
GET  /search-jobs/{jobId}
GET  /search-jobs/{jobId}/events
POST /search-jobs/{jobId}/cancel

The execution path becomes:

Create job
    ↓
Execute work independently
    ↓
Persist progress and results
    ↓
Expose progress through a stream

Under this contract:

• A disconnected browser does not automatically cancel the job.
• Cancellation is an explicit operation.
• The client can retrieve the current state after reconnecting.
• Stable result identifiers support deduplication.
• An explicit terminal state distinguishes completion from interruption.

A proposed terminal event:

event: done
id: 148
data: {"jobId":"job-109","status":"completed","resultCount":73}

The count above is illustrative, not a reported result.

Reconnection is not replay

MDN documents automatic reconnection behavior for EventSource and the use of event IDs. However, retaining missed events and deciding what to replay remain application responsibilities. developer.mozilla

If the client consumes SSE through fetch, I would explicitly implement and test its reconnection behavior rather than assume it inherits the behavior of EventSource.

For this design, a reconnect request should either:

1. Resume from an accepted cursor, or
2. Return a fresh snapshot and establish a new event position.

The server should define what happens when an old cursor can no longer be served. Silent gaps are not an acceptable recovery contract.

8. Use AI to Challenge the Explanation

An AI assistant can be useful here—but the prompt should not smuggle an unproven cause into the task.

A weak prompt:

Explain why MetaMask terminates my SSE connection.

A better prompt:

Observation:
Initial search results appeared after MetaMask was disabled.

Unknown:
Whether MetaMask caused the earlier failure.

Tasks:
1. Separate observations from causal claims.
2. Propose competing explanations.
3. Design the smallest experiment that distinguishes them.
4. State what result would weaken each explanation.
5. Do not invent extension internals.
6. Identify missing evidence before proposing a patch.

Then require an evidence structure:

Claim
Supporting observation
Conflicting observation
Missing evidence
Next discriminating test

I would also separate patch generation from patch acceptance.

A proposed patch must demonstrate:

• A reproducible failure.
• A test that detects it.
• A change that makes that test pass.
• Regression tests for neighboring behavior.
• A clear statement of what remains unverified.

An articulate explanation is not an experimental result.

9. Define Completion Before Declaring Victory

For the proposed investigation, I would not close the issue merely because:

• The console became quiet.
• The first results appeared.
• One retry succeeded.
• Disabling an extension changed the behavior once.

I would close it with either:

A supported root cause

A reproducible failure, a discriminating experiment, and a validated correction.

An explicitly unresolved cause

A documented observation, unsuccessful reproduction attempts, remaining hypotheses, and improved instrumentation.

The second outcome is not a failed investigation. It is a defensible limit on what the evidence supports.

Meanwhile, the architecture should pass a separate recovery test:

Disconnect the client during a search, reconnect, and verify that persisted results remain available without creating a duplicate job or misreporting completion.

Conclusion

The MetaMask error was a legitimate clue. The successful retry was a useful observation. Neither justified the full story that initially seemed to connect them.

The engineering opportunity was larger than identifying one extension:

• Separate transport health from job health.
• Separate application failures from telemetry noise.
• Test active and silent streams independently.
• Make recovery behavior explicit.
• Ask AI for falsifiable experiments rather than confident explanations.

A clean console is not proof of a healthy system. A successful retry is not proof of a root cause.

Build tests that can tell the difference.

created by : https://almodarresieh.github.io/