[ICE]: rustdoc `unexpected async fn return type`

[matthiaskrgr]

Code

rustdoc file.rs --edition=2018
this compiles with rustc but ices rustdoc

#![feature(fn_delegation)]

trait Trait {
    async fn foo(&self) {
        
    }
}
reuse Trait::foo;

fn main() {}

Meta

rustc --version --verbose:

rustdoc 1.98.0-nightly (57d06900f 2026-05-27)
binary: rustdoc
commit-hash: 57d06900fd7d9ee06d3a7f323bb77f17ab3cfaf8
commit-date: 2026-05-27
host: x86_64-unknown-linux-gnu
release: 1.98.0-nightly
LLVM version: 22.1.6

Error output

warning: the feature `fn_delegation` is incomplete and may not be safe to use and/or cause compiler crashes
 --> rustdoc.rs:1:12
  |
1 | #![feature(fn_delegation)]
  |            ^^^^^^^^^^^^^
  |
  = note: see issue #118212 <https://github.com/rust-lang/rust/issues/118212> for more information
  = note: `#[warn(incomplete_features)]` on by default


thread 'rustc' (3518636) panicked at src/librustdoc/clean/types.rs:1585:13:
unexpected async fn return type
stack backtrace:
   0:     0x7f345829a939 - <<std[eaf14822774233d1]::sys::backtrace::BacktraceLock>::print::DisplayBacktrace as core[f7871c8529df0cd1]::fmt::Display>::fmt
   1:     0x7f3458a20888 - core[f7871c8529df0cd1]::fmt::write
   2:     0x7f34582b1626 - <std[eaf14822774233d1]::sys::stdio::unix::Stderr as std[eaf14822774233d1]::io::Write>::write_fmt
   3:     0x7f3458270b5e - std[eaf14822774233d1]::panicking::default_hook::{closure#0}
   4:     0x7f345828e273 - std[eaf14822774233d1]::panicking::default_hook
   5:     0x7f345708ade1 - std[eaf14822774233d1]::panicking::update_hook::<alloc[8b32aeac9c6adb]::boxed::Box<rustc_driver_impl[535bed017e0d96c2]::install_ice_hook::{closure#1}>>::{closure#0}
   6:     0x7f345828e552 - std[eaf14822774233d1]::panicking::panic_with_hook
   7:     0x7f3458270c54 - std[eaf14822774233d1]::panicking::panic_handler::{closure#0}
   8:     0x7f3458267929 - std[eaf14822774233d1]::sys::backtrace::__rust_end_short_backtrace::<std[eaf14822774233d1]::panicking::panic_handler::{closure#0}, !>
   9:     0x7f345827268d - __rustc[eb98ed7eb95e5295]::rust_begin_unwind
  10:     0x7f3454ebcf2c - core[f7871c8529df0cd1]::panicking::panic_fmt
  11:     0x556d26809bdc - <rustdoc[37593b338b77beff]::clean::types::Type>::sugared_async_return_type
  12:     0x556d2681fcd9 - rustdoc[37593b338b77beff]::clean::clean_function
  13:     0x556d2674ad4a - rustdoc[37593b338b77beff]::clean::clean_maybe_renamed_item::{closure#0}
  14:     0x556d26827340 - rustdoc[37593b338b77beff]::clean::clean_doc_module
  15:     0x556d268191fe - rustdoc[37593b338b77beff]::core::run_global_ctxt
  16:     0x556d2672e481 - rustdoc[37593b338b77beff]::main_args::{closure#2}::{closure#0}
  17:     0x556d26725437 - rustc_interface[83c0f8112acc708a]::interface::run_compiler::<(), rustdoc[37593b338b77beff]::main_args::{closure#2}>::{closure#1}
  18:     0x556d266574a6 - std[eaf14822774233d1]::sys::backtrace::__rust_begin_short_backtrace::<rustc_interface[83c0f8112acc708a]::util::run_in_thread_with_globals<rustc_interface[83c0f8112acc708a]::util::run_in_thread_pool_with_globals<rustc_interface[83c0f8112acc708a]::interface::run_compiler<(), rustdoc[37593b338b77beff]::main_args::{closure#2}>::{closure#1}, ()>::{closure#0}, ()>::{closure#0}::{closure#0}, ()>
  19:     0x556d2676d29d - <std[eaf14822774233d1]::thread::lifecycle::spawn_unchecked<rustc_interface[83c0f8112acc708a]::util::run_in_thread_with_globals<rustc_interface[83c0f8112acc708a]::util::run_in_thread_pool_with_globals<rustc_interface[83c0f8112acc708a]::interface::run_compiler<(), rustdoc[37593b338b77beff]::main_args::{closure#2}>::{closure#1}, ()>::{closure#0}, ()>::{closure#0}::{closure#0}, ()>::{closure#1} as core[f7871c8529df0cd1]::ops::function::FnOnce<()>>::call_once::{shim:vtable#0}
  20:     0x7f3459b9d1ec - <std[eaf14822774233d1]::sys::thread::unix::Thread>::new::thread_start
  21:     0x7f34530981b9 - <unknown>
  22:     0x7f345311d21c - <unknown>
  23:                0x0 - <unknown>

error: the compiler unexpectedly panicked. This is a bug

note: we would appreciate a bug report: https://github.com/rust-lang/rust/issues/new?labels=C-bug%2C+I-ICE%2C+T-rustdoc&template=ice.md

note: please make sure that you have updated to the latest nightly

note: please attach the file at `/tmp/im/rustc-ice-2026-05-28T04_29_37-3518627.txt` to your bug report

note: rustc 1.98.0-nightly (57d06900f 2026-05-27) running on x86_64-unknown-linux-gnu

query stack during panic:
end of query stack
warning: 1 warning emitted

Backtrace

<backtrace>

[Dnreikronos]

Hi @GuillaumeGomez, I see you're assigned here. I looked into this one and have a fix ready, so I wanted to check with you before opening a PR in case you're already on it.

The panic is in clean_fn_decl_with_params (src/librustdoc/clean/mod.rs). It sugars the async return type whenever the fn header is async:

if let Some(header) = header && header.is_async() {
    output = output.sugared_async_return_type();
}

For a delegated async fn (reuse Trait::foo), the return type is InferDelegation, which clean_ty lowers to Type::Infer. That isn't the impl Future<Output = ...> shape sugared_async_return_type expects, so it hits the else and panics.

The sibling clean_poly_fn_sig already guards the same call with if let Type::ImplTrait(_) = output; the HIR path just doesn't. Adding that guard clears the ICE for every async delegation shape I tried (unit and non-unit returns, both at module level and inside an impl). I've got a check-pass regression test, and the full rustdoc-ui suite still passes.

One thing I left alone on purpose: rustdoc renders delegated fns with inferred types, like pub async fn unit<Self>(self: _) -> _. That's pre-existing and not specific to async. Plain sync delegation prints the same thing (pub fn sync_unit<Self>(self: _) -> _), since every delegation type cleans to Infer. Feels like a separate issue from the ICE, so I left it out. Happy to file it if it isn't tracked already.

If you haven't started on this, I'm glad to send the PR. If you've already got it in hand, no worries, I'll leave it with you.

[GuillaumeGomez]

Yeah basically the -> _ is where I'm currently stuck as I'd like to get the actual output.

[Dnreikronos]

@GuillaumeGomez the -> _ comes from the cleaning path more than from the delegation itself. clean_fn_decl_with_params cleans decl.output straight off the HIR, and for a reuse item that node is TyKind::InferDelegation. clean_ty lowers that to Type::Infer, which prints as _. The HIR honestly has no resolved type there yet; it gets filled in later during analysis. Same reason the inputs come out as self: _.

The resolved signature does exist though, just on the ty side. lower_delegation_ty pulls it out of tcx.inherit_sig_for_delegation_item(def_id), and tcx.fn_sig(def_id) is built on top of that, so tcx.fn_sig(def_id).instantiate_identity().skip_norm_wip() hands you the real PolyFnSig with the inputs and output filled in. We already clean that exact shape with clean_poly_fn_sig, and it does the async sugaring and the asyncness check itself. It's the same thing build_function does for inlined items, so this isn't a new path, just applying it where the HIR can't help.

What I'd suggest: in the HIR fn path, detect a delegation and clean the middle signature for the decl instead of the HIR one. Detection is cheap: tcx.hir_opt_delegation_sig_id(def_id).is_some(), or decl.opt_delegation_sig_id(). Roughly:

if cx.tcx.hir_opt_delegation_sig_id(def_id).is_some() {
    let sig = cx.tcx.fn_sig(def_id).instantiate_identity().skip_norm_wip();
    let decl = clean_poly_fn_sig(cx, Some(def_id), sig);
    return Box::new(Function { decl, generics }); // generics stay HIR-cleaned
}

That resolves -> _ to the real return type and clears up self: _ as a bonus (the middle path renders &self correctly). It also makes the ICE guard moot on this path, since clean_poly_fn_sig only sugars when the output is impl Trait and asyncness reports async.

A couple of things I'd keep separate:

• I'd only clean the decl from the ty side and leave the generics HIR-cleaned. Rerouting the whole function through build_function-style cleaning would also pull generics from the middle layer, which is a bigger change, and it drags in the <Self> rendering. That one shows up for plain sync delegation too, so it feels like its own issue rather than part of this fix.
• Worth checking on the test: asyncness(delegation_def_id) needs to report async for the sugaring to fire, otherwise the output renders as impl Future<...> instead of the sugared form. Still better than _, but worth confirming.

The only real plumbing is that clean_function / clean_fn_decl_with_params don't get the item DefId today, so it has to be threaded in from the callers, which all have it.

[GuillaumeGomez]

@Dnreikronos I won't have time to come back to this issue before a few days and you seem to already know how to fix it so releasing my assignment. r? me on your PR please. :)

[rustbot]

Error: r? is only allowed on PRs.

Please file an issue on GitHub at triagebot if there's a problem with this bot, or reach out on #triagebot on Zulip.