Migrating from the Legacy Resolution API¶

The Analysis API resolution surface was redesigned as part of KT-66039. This guide maps the old API to the new one. If you are not yet familiar with the new shape, read Resolution Fundamentals first — this guide assumes you know the old API.

Why the API changed¶

Five user-facing pains motivated the redesign:

1. KtReference was a PSI/IDE infrastructure leak. It belongs to IntelliJ infrastructure, yet the Analysis API required reaching for element.mainReference.resolveTo...(), smuggling a syntax-layer concept into the semantic contract.
2. Discoverability suffered. To resolve via the Analysis API, you first had to know to call .mainReference on a KtElement and then invoke resolveTo...() on the resulting KtReference. Nothing about the API surface advertised this idiom, so callers who did not already know it fell back to the more familiar PsiReference.resolve() instead.
3. Result types were under-specified. resolveToSymbol() returned KaSymbol? everywhere; resolveToCall() returned a KaCallInfo? over a generic KaCall. Callers had to as?-cast to anything specific.
4. KaPartiallyAppliedSymbol was a useless wrapper. Receivers, signature, and type-argument mapping had to be unwrapped through an extra layer. The new KaSimpleCall exposes all of this inline; the new compound calls expose named sub-call accessors (variableCall, getterCall, setterCall, operationCall).
5. KtElement.resolveToCall accepted any KtElement. Nothing in the type told you whether resolution would succeed or what it would return. KtReference filled the gap for everything resolveToCall could not handle — so callers had to maintain two parallel resolution mechanisms.

The new API replaces both KtReference-based resolution and KtElement.resolveToCall with a single, type-driven surface: specialized resolveSuccessfulSymbol / resolveSuccessfulCall methods on concrete PSI types, plus the marker interfaces KtResolvable and KtResolvableCall for the generic case.

Migration rules¶

Two rules cover almost all sites:

1. Use the specialized method on the concrete PSI type whenever possible. If you know the element is a KtCallElement, write callElement.resolveSuccessfulCall() — you get back a KaFunctionCall<*>? directly. Each specialization narrows the return type, so type checks and casts you used to write disappear.
2. When the PSI type is genuinely unknown, narrow with a safe as? cast. To check whether the element implements KtResolvable or KtResolvableCall.

// Specialized form (preferred)
val call: KaFunctionCall<*>? = callElement.resolveSuccessfulCall()

// Generic form (only when the element type is unknown)
val call: KaSimpleOrMultiCall? =
    (element as? KtResolvableCall)?.resolveSuccessfulCall()

Old → new matrix¶

Result wrapper: KaCallInfo → KaCallResolutionAttempt¶

resolveToCall() returned a KaCallInfo; tryResolveCall() returns a KaCallResolutionAttempt. The new one carries KaSimpleCall<*, *> payloads instead of bare KaCall, and splits simple-call attempts from multi-call ones (compound / for / delegated property).

// Old, total
val diagnostic = (info as? KaErrorCallInfo)?.diagnostic

// New, NOT total - misses failed compound calls
val diagnostic = (attempt as? KaSimpleCallResolutionError)?.diagnostic

// New, total
val diagnostic = attempt.errors.firstOrNull()?.diagnostic

Multi-call attempts (KaForLoopCallResolutionAttempt, KaDelegatedPropertyCallResolutionAttempt, KaCompound*CallResolutionAttempt) expose call: KaMultiCall? plus per-step simpleAttempts: List<KaSimpleCallResolutionAttempt>; the old KaCallInfo had no equivalent — these calls were resolved indirectly.

Call hierarchy: KaCall → KaSimpleOrMultiCall¶

A successful resolution used to hand back a KaCall; now it hands back a KaSimpleOrMultiCall. KaFunctionCall and KaVariableAccessCall keep their names but are now KaSimpleCalls (so their data is inline — see below); compound, for-loop, and delegated-property calls are KaMultiCalls.

Candidate hierarchy: KaCallCandidateInfo → KaCallCandidate¶

collectCallCandidates() (was resolveToCallCandidates()) returns KaCallCandidates instead of KaCallCandidateInfo s. The hierarchy is identical; only the names change and candidate widens from KaCall to KaSimpleOrMultiCall.

Calls¶

Inline access on a KaSimpleCall¶

Every *PartiallyAppliedSymbol access becomes a direct field on the call.

Subtypes you may have used¶

Compound calls (+=, ++, --, a[i] += v, by, for)¶

For-loops and delegated properties did not have a separate API in the old world; they were either resolved indirectly or required custom code. The new API exposes them as first-class multi-calls: KaForLoopCall and KaDelegatedPropertyCall, with matching attempt types KaForLoopCallResolutionAttempt and KaDelegatedPropertyCallResolutionAttempt.

Symbol resolution¶

Emulating mainReference.resolveToSymbols()¶

For navigation, find-usages, and similar features, the old mainReference.resolveToSymbols() returned every symbol the compiler considered — a kitchen-sink that included results from both call resolution (precise targets) and plain symbol resolution. The new API does not bundle these two into a single call, but the recipe is short:

@OptIn(KaExperimentalApi::class, KtExperimentalApi::class)
context(session: KaSession)
fun resolveToSymbols(element: KtElement): Collection<KaSymbol> {
    // 1. Prefer symbols extracted from a resolved call.
    //    Call resolution is more precise: a constructor call,
    //    for instance, points at the constructor, not the class.
    //
    //    `KtOperationReferenceExpression` is excluded on purpose. Its call resolution
    //    forwards to the parent expression and would also surface intermediate reads
    //    (e.g. the `get` of a compound `a[i] += v`), whereas the legacy
    //    `resolveToSymbols()` returned only the symbols the operator itself contributes
    //    (`plus`, `set`). Skipping the call step lets it fall through to
    //    `tryResolveSymbols()` below, which preserves that behavior.
    val callSymbols = (element as? KtResolvableCall)?.takeUnless { it is KtOperationReferenceExpression }
        ?.tryResolveCall()
        ?.calls
        ?.flatMap(KaSimpleOrMultiCall::symbols)
        ?.takeUnless(List<KaSymbol>::isEmpty)

    if (callSymbols != null) return callSymbols

    // 2. Fall back to plain symbol resolution.
    return (element as? KtResolvable)
        ?.tryResolveSymbols()
        ?.symbols
        .orEmpty()
}

This pattern is the formal way to migrate a mainReference.resolveToSymbols() call site that needs the broadest possible result.

Common migration patterns¶

The recipes below assume the opt-ins from the note at the top of this page are in scope.

resolveToCall¶

resolveSuccessfulCall() returns only the successfully resolved call — it is defined as tryResolveCall()?.successful. It is therefore the faithful replacement for the successful* reductions, not the single* ones: the single* helpers read KaCallInfo.calls, which for an error call is the candidate list, so they also return the sole candidate of an unresolved call. Classify the old reduction before migrating:

The common success-only case — a resolved single function call — collapses to one call, since resolveSuccessfulCall() over a KtCallElement already returns KaFunctionCall<*>?:

// Old (success-only)
val call = callExpression.resolveToCall()
    ?.successfulFunctionCallOrNull()
    ?: return

// New
val call = callExpression.resolveSuccessfulCall() ?: return

The candidate-tolerant singleFunctionCallOrNull() is not equivalent — resolveSuccessfulCall() drops the sole candidate of a failed call that singleFunctionCallOrNull() would have returned. Preserve that behavior with tryResolveCall():

// Old (candidate-tolerant)
val call = callExpression.resolveToCall()
    ?.singleFunctionCallOrNull()
    ?: return

// New
val call = callExpression.tryResolveCall()
    ?.single
    ?.function
    ?: return

If you only need the called symbol, skip the call entirely and use the specialized resolveSuccessfulSymbol():

// Old
val symbol = callExpression.resolveToCall()
    ?.successfulFunctionCallOrNull()
    ?.symbol
    ?: return

// New
val symbol = callExpression.resolveSuccessfulSymbol() ?: return

KaPartiallyAppliedSymbol is gone, so partiallyAppliedSymbol.signature / .symbol chains flatten:

// Old
val id = callExpression.resolveToCall()
    ?.successfulFunctionCallOrNull()
    ?.partiallyAppliedSymbol?.signature?.callableId

// New
val id = callExpression.resolveSuccessfulCall()?.symbol?.callableId
// or:   callExpression.resolveSuccessfulSymbol()?.callableId

When the receiver is only statically a KtExpression / KtElement, cast to the marker interface and narrow the result:

// Old
val call = expression.resolveToCall()?.successfulFunctionCallOrNull()

// New
val call = (expression as? KtResolvableCall)?.resolveSuccessfulCall()?.function

The same cast covers other call shapes. Variable access:

// Old
val access = expression.resolveToCall()?.successfulVariableAccessCall()

// New
val access = (expression as? KtResolvableCall)?.resolveSuccessfulCall()?.variable

A member call resolved through successfulCallOrNull<KaCallableMemberCall<*, *>>():

// Old
val symbol = expression.resolveToCall()
    ?.successfulCallOrNull<KaCallableMemberCall<*, *>>()
    ?.partiallyAppliedSymbol?.symbol

// New
val symbol = (expression as? KtResolvableCall)?.resolveSuccessfulCall()?.simple?.symbol

Trap — iterating candidate calls. resolveSuccessfulCall() is null whenever resolution fails, which is exactly the case a .calls loop wants to inspect. Migrate .calls to tryResolveCall()?.calls, not resolveSuccessfulCall():

// Old
for (call in call.resolveToCall()?.calls.orEmpty()) {
    // ...
}

// New
for (call in call.tryResolveCall()?.calls.orEmpty()) {
    // ...
}

When a helper switched over a resolved KaCall, widen its parameter to KaSimpleOrMultiCall (the type resolveSuccessfulCall() now returns) and drop the successfulCallOrNull<KaCall>() unwrapping at the call site. Deprecated subtype casts also disappear: as? KaSimpleFunctionCall becomes the function property.

resolveToCallCandidates¶

A rename plus a type rename: resolveToCallCandidates() → collectCallCandidates(), and the element type KaCallCandidateInfo → KaCallCandidate (the .candidate and .isInBestCandidates members are unchanged):

// Old
fun handle(candidates: List<KaCallCandidateInfo>) {
}

handle(callExpression.resolveToCallCandidates())

// New
fun handle(candidates: List<KaCallCandidate>) {
}

handle(callExpression.collectCallCandidates())

On a generic receiver, cast first:

// Old
val first = expression.resolveToCallCandidates()
    .firstOrNull()
    ?.candidate as? KaFunctionCall<*>

// New
val candidates = (expression as? KtResolvableCall)?.collectCallCandidates()
val first = candidates?.firstOrNull()?.candidate as? KaFunctionCall<*>

collectCallCandidates() returns all overload-resolution candidates; resolveSuccessfulCall() returns only the single most-specific result. Use candidates when you need to reason about ambiguity, the resolved call otherwise.

resolveToSymbol¶

Resolve on the element, not on its mainReference. The specialized overload returns a narrower symbol type:

// Old
val symbol = operationReference.mainReference.resolveToSymbol() as? KaFunctionSymbol
    ?: return

// New
val symbol = operationReference.resolveSuccessfulSymbol() as? KaFunctionSymbol
    ?: return

A this expression resolves directly — no instanceReference.mainReference:

// Old
val symbol = thisExpression.instanceReference
    .mainReference
    .resolveToSymbol()

// New
val symbol = thisExpression.resolveSuccessfulSymbol()

When the static type is only KtExpression, narrow to KtResolvable:

// Old
val symbol = expression.mainReference?.resolveToSymbol() as? KaValueParameterSymbol
    ?: return

// New
val symbol = (expression as? KtResolvable)?.resolveSuccessfulSymbol() as? KaValueParameterSymbol
    ?: return

// Old: resolves the callee reference
val symbol = callExpression.calleeExpression
    ?.mainReference
    ?.resolveToSymbol() as? KaConstructorSymbol

// New: resolves the call element -> the constructor itself
val symbol = callExpression.resolveSuccessfulSymbol() as? KaConstructorSymbol

resolveToSymbols¶

resolveToSymbols() returned a collection. Both common reductions over it map to the single-result resolveSuccessfulSymbol(), but with a warning:

// Old (exact, single target)
val symbol = element.mainReference.resolveToSymbols().singleOrNull()

// New
val symbol = element.resolveSuccessfulSymbol()
// or:       (element as? KtResolvable)?.resolveSuccessfulSymbol()

// Old (tolerated ambiguity, picked one)
val symbol = element.mainReference.resolveToSymbols().firstOrNull()
// New (returns null on more than one target!)
val symbol = element.resolveSuccessfulSymbol()

resolveSuccessfulSymbol() is an exact match for .singleOrNull() on valid code — both yield a result only for a single, unambiguous target. It is not a faithful match for .firstOrNull(), which silently chose one of several ambiguous symbols: resolveSuccessfulSymbol() returns null when there is more than one target. Note also that resolveSuccessfulSymbol() and resolveSuccessfulSymbols() return only successful targets, whereas the old resolveToSymbols() also exposed candidate symbols on invalid code. If a call site genuinely needs every candidate — ambiguous or red — migrate to resolveSuccessfulSymbols() for ambiguity, or to the emulation recipe above (tryResolveCall()?.calls / tryResolveSymbols()?.symbols) for the full best-effort set, not resolveSuccessfulSymbol().

What about KtReference?¶

Kotlin references have become part of the IntelliJ IDEA Kotlin plugin. The Analysis API no longer uses them.

The extensions KtReference.resolveToSymbols() and KtReference.resolveToSymbol() remain available as a backward-compatibility surface; they are not annotated @Deprecated outright, but the modern flow does not pass through KtReference at all. Resolve directly on the KtElement instead, using the specialized method or a safe as? narrowing to KtResolvable.

Two KtReference extensions are explicitly deprecated and have moved to KtSimpleNameExpression:

• KtReference.isImplicitReferenceToCompanion() → (element as? KtSimpleNameExpression)?.isImplicitReferenceToCompanion == true.
• KtReference.usesContextSensitiveResolution → (element as? KtSimpleNameExpression)?.usesContextSensitiveResolution == true.

Opting in¶

All entry points described here are annotated @KaExperimentalApi. You must opt in at the call site:

@OptIn(KaExperimentalApi::class)
fun myUsage(element: KtCallElement) = analyze(element) {
        element.resolveSuccessfulCall()
    }

When a snippet names the KtResolvable / KtResolvableCall marker interfaces directly (the generic fallback form), add the second opt-in — the markers themselves are annotated @KtExperimentalApi:

@OptIn(KaExperimentalApi::class, KtExperimentalApi::class)
fun myUsage(element: KtElement) = analyze(element) {
        (element as? KtResolvableCall)?.resolveSuccessfulCall()
    }

This is the only deliberate friction during migration: the rest of the surface is designed to require no manual cast, no wrapper unwrapping, and no parallel KtReference fallback.