Skip to content

Promise type unwrapping confusion

Quick summary

Your async function returns Promise<T> but TypeScript infers Promise<Promise<T>> — async already wraps the return in a Promise.

Why this happens

  • An async function explicitly returns a Promise, causing double wrapping: async function f(): Promise<Promise<T>>

  • You awaited a value inside an async function and returned it, not realizing the await already unwrapped the Promise

  • A non-async function returns a value that is accidentally typed as Promise<T> instead of T

Minimal example

✗ Broken code
async function getData(): Promise<Promise<string>> {
  return Promise.resolve('hello'); // double-wrapped!
}
// Type is Promise<Promise<string>>, but runtime is Promise<string>
✓ Fixed code
async function getData(): Promise<string> {
  return 'hello'; // async wraps it in Promise
}
// Or non-async:
function getData(): Promise<string> {
  return Promise.resolve('hello');
}

Async functions automatically wrap the return value in a Promise, so the return type should be Promise<T>, not Promise<Promise<T>>.

How to diagnose

  • Hover over the function return type to see if it is doubly wrapped as Promise<Promise<T>>

  • Check if the function is async — async functions automatically wrap returns in Promise

  • Log the runtime value to see if it is a Promise object or an unwrapped value

How to fix

  • Remove the explicit Promise wrapper from the return type of async functions — async handles it

  • Remove unnecessary await if you are returning a Promise from an async function

  • Use Promise.resolve(value) to explicitly wrap a value in a Promise when needed

How to prevent

  • Remember that async functions automatically wrap return values in Promise — do not double-wrap

  • Use Awaited<T> (TS 4.5+) to unwrap Promise types in type-level code

Related Resources

Related Glossary

Related Lessons

← Back to language