ContextPropagation does not work for suspend endpoints when coroutine suspension occurs

[mateusz-nalepa]

Hey!

Context

I've noticed, that ContextPropagation does not work by default for endpoint market with suspend, when coroutine suspension occurs, for example delay.

I've created new Spring Boot app, added given dependencies and I thought, that it will work out of the box:

implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core")
implementation("org.jetbrains.kotlinx:kotlinx-coroutines-reactor")

implementation("io.micrometer:micrometer-tracing")
implementation("io.micrometer:context-propagation")
implementation("org.springframework.boot:spring-boot-starter-opentelemetry")
implementation("org.springframework.boot:spring-boot-starter-aspectj")

For given endpoint traceId is not propagated. Log After delay does not have traceId inside, as a result, endpoint throws status code 500:

@GetMapping("/not-work")
suspend fun notWork(): String {
    logger.info("Before delay")
// 2026-07-02T21:00:11.033+02:00  INFO 13795 --- [suspend-context-propagation] [nio-8080-exec-5]
// [76a9324e0135954444f807074b4f6f6b-649f59948d07aa64] c.n.s.DemoController : Before delay


    delay(1000.milliseconds)
    logger.info("After delay")
// 2026-07-02T21:00:12.035+02:00  INFO 13795 --- [suspend-context-propagation] [DefaultExecutor] 
//[                                                 ] c.n.s.DemoController : After delay


    return tracer.currentSpan()!!.context().traceId()
}

Versions

Java Version - 25
plugins {
	kotlin("jvm") version "2.3.21"
	kotlin("plugin.spring") version "2.3.21"
	id("org.springframework.boot") version "4.1.0"
	id("io.spring.dependency-management") version "1.1.7"
}

How to reproduce

• Clone repository
  https://github.com/mateusz-nalepa/suspend-context-propagation
• Run SuspendContextPropagationApplication
• Run curl localhost:8080/not-work

Expected behaviour

• Context-propagation works
• There is maybe some custom param, whatever, which enables context-propagation

Workaround

I can use some workarounds for that issue.

First workaround

I can add withContext(PropagationContextElement()) on the beginning of every endpoint

Second workaround

Given Aspect works without any problems

@Aspect
@Component
class GlobalWebMvcCoroutineContextAspect {

    @Around("within(@org.springframework.web.bind.annotation.RestController *)")
    fun injectTraceContextGlobally(joinPoint: ProceedingJoinPoint): Any? {
        val args = joinPoint.args

        if (args.isEmpty() || args.last() !is Continuation<*>) {
            return joinPoint.proceed()
        }

        val originalContinuation = args.last() as Continuation<Any?>

        val wrappedContinuation = object : Continuation<Any?> {
            override val context: CoroutineContext
                get() = originalContinuation.context + PropagationContextElement()

            override fun resumeWith(result: Result<Any?>) {
                originalContinuation.resumeWith(result)
            }
        }

        args[args.size - 1] = wrappedContinuation
        return joinPoint.proceed(args)
    }
}

I'm open to any feedback. I can try to fix this, if needed.

[codingkiddo]

Hi team, I looked into this and it seems related to automatic use of PropagationContextElement for suspend function invocation, similar to #35485.

I can try to reproduce this with a Spring MVC Kotlin suspend controller test and investigate whether the MVC handler invocation path needs to pass/include PropagationContextElement when invoking suspend endpoints.

Would that be a reasonable direction before I start a PR?

[mateusz-nalepa]

Hi @codingkiddo ,
I've looked into that topic deeper, and it looks like both for WebMvc and WebFlux the following dependencies are needed to use automatic context propagation:

implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core")
implementation("org.jetbrains.kotlinx:kotlinx-coroutines-reactor")

Additionally, in order to enable context-propagation:

WebMvc

The following code is needed:

Hooks.enableAutomaticContextPropagation()

WebFlux

In WebFlux, the following flag can be used:

spring:
  reactor:
    context-propagation: auto

Thoughts

Maybe there could be one flag that enabled Automatic Context Propagation?

Right now there is also another flag for @async methods: spring.task.execution.propagate-context

For example:

spring:
  context-propagation: auto/limited

Which should enable context-propagation.

Additional thought about cognitive load

Right now the hardest part for me was fact, that implementation("org.jetbrains.kotlinx:kotlinx-coroutines-reactor") is needed, in order to make it work, even for WebMvc applications. But it makes sense, since suspending functions are being converted to reactive-streams publisher internally in Spring:
org.springframework.web.method.support.InvocableHandlerMethod#invokeSuspendingFunction

There is info about this in docs https://docs.spring.io/spring-framework/reference/languages/kotlin/coroutines.html#coroutines.propagation
but still, cognitive-load is the hardest part in all of that in my opinion.

I'm open to any feedback, comments about that.

[codingkiddo]

Thanks @mateusz-nalepa, this makes sense.

From what I understand, the actual propagation mechanism is already available, but the tricky part is discoverability:

1. WebMvc suspend endpoints still need kotlinx-coroutines-reactor because Spring internally adapts suspending functions through reactive Publisher invocation.
2. For WebMvc, users need to explicitly enable Reactor automatic context propagation via Hooks.enableAutomaticContextPropagation().
3. For WebFlux in Spring Boot, spring.reactor.context-propagation=auto can enable it.
4. spring.task.execution.propagate-context is a separate Boot-level setting for @Async/task execution.

The idea of a unified spring.context-propagation property sounds useful, but I think that would probably belong to Spring Boot rather than Spring Framework.

For this Spring Framework issue, would a documentation improvement be acceptable? I can try to update the Kotlin coroutines context propagation section to make the WebMvc + kotlinx-coroutines-reactor requirement and the Boot/WebMvc/WebFlux configuration differences more explicit.

[mateusz-nalepa]

Hey @codingkiddo
I think improving the documentation sounds really good. But maybe let's wait for the Spring Team, since this issue currently has a waiting-for-triage status. There might be some important context we're not aware of that could be helpful.