Introduction

When Redux promise middleware leaves a promise unresolved in your reducer, the problem is usually action shape mismatch or middleware ordering, not the promise itself. Different middleware packages expect slightly different action contracts. If your action includes extra fields in the wrong structure, the middleware may skip transformation and pass raw data through.

Understand Which Middleware You Are Using

redux-promise and redux-promise-middleware do similar jobs but not identical jobs.

• redux-promise expects payload itself to be a promise.
• redux-promise-middleware supports lifecycle suffix actions and also expects promise data in expected locations.

Always check package-specific docs before debugging reducer behavior.

npm ls redux-promise redux-promise-middleware

If you are unsure which package is active, inspect store setup first.

Correct Action Shape for Promise Middleware

For most promise middleware flows, keep payload as the promise and place metadata separately.

1import axios from "axios";
2
3export const fetchUsers = () => ({
4  type: "FETCH_USERS",
5  payload: axios.get("/api/users"),
6  meta: { source: "users-page" }
7});

This gives middleware a clear promise target and keeps reducers predictable.

If you wrap the promise deeply, middleware may not detect it.

1// Risky for many middleware variants
2{
3  type: "FETCH_USERS",
4  payload: {
5    request: axios.get("/api/users")
6  }
7}

Unless your middleware explicitly supports that schema, it will treat payload as plain object.

Middleware Order Matters

Middleware are composed left to right, and order changes behavior.

1import { applyMiddleware, createStore } from "redux";
2import promiseMiddleware from "redux-promise-middleware";
3import thunk from "redux-thunk";
4
5const store = createStore(
6  rootReducer,
7  applyMiddleware(thunk, promiseMiddleware())
8);

If a preceding middleware consumes or transforms actions unexpectedly, promise middleware may never see a real promise payload.

A useful debugging tactic is to add a logger after promise middleware and inspect dispatched lifecycle actions.

Reducer Contract for Lifecycle Actions

With redux-promise-middleware, reducers should handle pending, fulfilled, and rejected variants.

1const initialState = {
2  items: [],
3  loading: false,
4  error: null
5};
6
7export function usersReducer(state = initialState, action) {
8  switch (action.type) {
9    case "FETCH_USERS_PENDING":
10      return { ...state, loading: true, error: null };
11    case "FETCH_USERS_FULFILLED":
12      return { ...state, loading: false, items: action.payload.data };
13    case "FETCH_USERS_REJECTED":
14      return { ...state, loading: false, error: action.payload };
15    default:
16      return state;
17  }
18}

If your reducer expects FETCH_USERS only, you might misinterpret transformed action flow as unresolved promise behavior.

Pattern for Thunk Plus Promise

If your project already uses thunk for side effects, avoid mixing patterns in the same action creator. Keep one clear convention:

• Either return plain object with promise payload for promise middleware.
• Or use thunk and await manually, dispatching explicit success and failure actions.

1export const fetchUsersThunk = () => async dispatch => {
2  dispatch({ type: "FETCH_USERS_PENDING" });
3  try {
4    const resp = await fetch("/api/users");
5    const data = await resp.json();
6    dispatch({ type: "FETCH_USERS_FULFILLED", payload: data });
7  } catch (err) {
8    dispatch({ type: "FETCH_USERS_REJECTED", payload: err, error: true });
9  }
10};

Mixed conventions are a common source of confusion.

Debugging Checklist

When promise remains unresolved in state flow, check this sequence:

1. Verify active middleware package.
2. Log raw dispatched action shape.
3. Confirm payload is actual promise.
4. Confirm middleware order in store configuration.
5. Confirm reducer handles transformed action types.

This catches most misconfigurations quickly.

Common Pitfalls

• Wrapping the promise in unexpected nested fields.
• Assuming all Redux promise middleware share one action schema.
• Putting middleware in an order that bypasses promise resolution logic.
• Handling only base action type while middleware dispatches lifecycle suffix types.
• Mixing thunk and promise conventions inconsistently across modules.

Summary

• Unresolved promise issues usually come from action shape or middleware setup.
• Keep payload as the direct promise unless your middleware contract says otherwise.
• Place extra metadata in meta rather than nested promise containers.
• Verify middleware order and reducer lifecycle action handling.
• Standardize one async action convention per codebase.