apache/hadoop · error · ServiceStateException

${name} cannot enter state ${proposed} from state ${state}

Error message

${name} cannot enter state ${proposed} from state ${state}

What it means

ServiceStateModel.checkStateTransition enforces the legal lifecycle matrix (NOTINITED->INITED/STOPPED, INITED->STARTED/STOPPED, STARTED->STOPPED; STOPPED is terminal). Proposing an illegal transition throws ServiceStateException "<name> cannot enter state <proposed> from state <state>". This is how misordered lifecycle calls (init after start, re-init after stop) are caught instead of silently corrupting service state.

Source

Thrown at hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/service/ServiceStateModel.java:132

    checkStateTransition(name, state, proposed);
    Service.STATE oldState = state;
    //atomic write of the new state
    state = proposed;
    return oldState;
  }

  /**
   * Check that a state tansition is valid and
   * throw an exception if not
   * @param name name of the service (can be null)
   * @param state current state
   * @param proposed proposed new state
   */
  public static void checkStateTransition(String name,
                                          Service.STATE state,
                                          Service.STATE proposed) {
    if (!isValidStateTransition(state, proposed)) {
      throw new ServiceStateException(name + " cannot enter state "
                                      + proposed + " from state " + state);
    }
  }

  /**
   * Is a state transition valid?
   * There are no checks for current==proposed
   * as that is considered a non-transition.
   *
   * using an array kills off all branch misprediction costs, at the expense
   * of cache line misses.
   *
   * @param current current state
   * @param proposed proposed new state
   * @return true if the transition to a new state is valid
   */
  public static boolean isValidStateTransition(Service.STATE current,
                                               Service.STATE proposed) {

View on GitHub (pinned to 2add963021)

Solutions

1. Follow the one-way lifecycle: init(conf) -> start() -> stop(), each at most once per instance.
2. To 'restart', build a new service instance rather than re-initing a stopped one.
3. Guard transitions with isInState() checks (e.g. only init when NOTINITED) before calling lifecycle methods.
4. In custom code use AbstractService.enterState via super calls so the model validates transitions for you.

Example fix

// before: reuse + re-init of a stopped service
stoppedService.init(newConf); // "cannot enter state INITED from state STOPPED"
// after: fresh instance per lifecycle
Service s = serviceClass.newInstance();
s.init(newConf);
s.start();

// Legal preconditions per transition
if (svc.isInState(Service.STATE.NOTINITED)) svc.init(conf);
if (svc.isInState(Service.STATE.INITED)) svc.start();
if (svc.isInState(Service.STATE.STARTED)) svc.stop();

boolean canInit(Service s)   { return s.isInState(Service.STATE.NOTINITED); }
boolean canStart(Service s) { return s.isInState(Service.STATE.INITED); }
boolean canStop(Service s)  { return s.isInState(Service.STATE.STARTED)
    || s.isInState(Service.STATE.INITED)
    || s.isInState(Service.STATE.NOTINITED); }

try {
  svc.init(conf);
} catch (ServiceStateException e) {
  // message: "cannot enter state INITED from state STARTED"
  // -> fix lifecycle ordering or build a fresh service instance
}

When it happens

Trigger: Calling service.init(conf) after start(); start() before init(); re-initializing a STOPPED service instead of creating a new instance; direct ServiceStateModel.enterState/checkStateTransition misuse in custom services; double init from overlapping threads bypassing AbstractService's synchronized guard.

Common situations: Test setups that init twice; restart logic that tries to reuse a stopped service instance; CompositeService calling child.init() inside serviceStart; refactors that move init calls.

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

Related errors

• ${name}: for this operation, the current service state must
• Cannot initialize service ${name}: null configuration
• Job in state {} instead of {}
• Can not open a folder
• key + ": Stream is closed!"

AI-assisted analysis of apache/hadoop@2add963021 (2026-08-22). Data as JSON: /api/errors/b2fe986efb1a491c. Report an issue: GitHub.