`Context` cancelation cause detection

[inancgumus]

What

Add deterministic reasons in the code why contexts are getting canceled.

Why

It's hard to determine why a Context is canceled, causing:

• Hiding race conditions
• Makes it difficult to understand system behavior
• Makes it difficult to fix bugs

Some examples where it is reported that the reason for canceling a Context is unclear:

• Data race during panic and running code on event loop #5534
• Context canceling causing browser integration tests to fail very often #5504
• Improve browser close detection constant timeout #4314
• Error when initializing networking: network.EnableParams #4417

How

• Use Context.WithCancelCause and friends.
• The error passed to these contexts should be chained with Errorf so that we can see the chain of cancellation reasons.

[LBaronceli]

Hi!

I tried to look into this issue before offering help, and I ended up experimenting with adding cancellation causes to make things clearer when contexts are canceled. This is the PR I’ve been working on (very much WIP):

master...LBaronceli:k6:add-deterministic-reasons-for-context-canceled-5535

What I did was add context.WithCancelCause in a few places (session.go and browser.go) and pass a reason when canceling, so that when something fails you can actually see why the context was canceled instead of just context canceled.

This seems to work in the sense that I can now see the cancellation reasons, but I’m clearly missing something about the expected behaviour. A lot of tests started failing because they don’t expect any error to come out of a context cancellation. For example:

=== NAME  TestBrowserNewPage
    browser_test.go:38: 
                Error Trace:    /Users/luisbaronceli/Documents/k6/internal/js/modules/k6/browser/tests/browser_test.go:38
                Error:          Received unexpected error:
                                closing a page: session context cancelled: session closed: sid:43CEBC1B35216E28B92F25797F7D73AD tid:A7B874DFDF9683CF38E061CE50A75738
                Test:           TestBrowserNewPage
time="2026-01-14T09:55:45+13:00" level=error msg="process with PID 72560 unexpectedly ended: signal: killed" category=browser elapsed="0 ms" source=browser
time="2026-01-14T09:55:45+13:00" level=error msg="process with PID 72538 unexpectedly ended: signal: killed" category=browser elapsed="0 ms" source=browser

So I’m not sure what the right direction is here.

Am I supposed to adjust the tests to expect these errors, or should the cancellation reason mostly be used for debugging/logging and not surface as an error in these cases? I might be misunderstanding where these errors are meant to be handled or swallowed.

Please feel free to ignore this if you don’t have time — I just wanted to check whether I’m thinking about this in the right way before going any further.

Thanks in advance!

[inancgumus]

Hi @LBaronceli, thanks for looking into this!

I looked at your code and some high-level ideas might be:

• Adding a cancel cause makes sense only for existing cancelable Contexts
• No need to log when returning an error
• Adding a Context helper func can be helpful, like:

// Pseudo-code that I haven't tried it yet.
func ContextErr(ctx context.Context) error {
    if err := context.Cause(ctx); err != nil {
        return fmt.Errorf("%w: %w", ctx.Err(), err)
    }
    return ctx.Err()
}

For the tests, yes, we might need to update them for the new use, too. We never swallow errors unless they are not explicitly returned but logged.

[LBaronceli]

Hi @inancgumus,

Thank you very much for the guidance, I really appreciate it!

I’ve updated my WIP PR based on the suggestions from your last comment:

• Added a ContextErr(ctx) helper that preserves ctx.Err() and appends context.Cause(ctx).
• Replaced ctx.Err() with ContextErr(ctx) on the places the value was being returned, and cleaned it from any logs.
• Swapped cancelable contexts from context.WithCancel to context.WithCancelCause where I found appropriate, and provided the causes on the existing cancel paths.

Would you mind taking a look when you have some time to check if this matches what you said on your previous comment?

PR: master...LBaronceli:k6:add-deterministic-reasons-for-context-canceled-5535

Thank you, again!