{"record":{"id":"e50c85be953a27c4","repo":"apache/hadoop","slug":"incorrect-state-to-start-a-new-value-state","errorCode":null,"errorMessage":"Incorrect state to start a new value: {state}","messagePattern":"Incorrect state to start a new value: (.+?)","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/io/file/tfile/TFile.java","lineNumber":569,"sourceCode":"\n    /**\n     * Obtain an output stream for writing a value into TFile. This may only be\n     * called right after a key appending operation (the key append stream must\n     * be closed).\n     * \n     * @param length\n     *          The expected length of the value. If length of the value is not\n     *          known, set length = -1. Otherwise, the application must write\n     *          exactly as many bytes as specified here before calling close on\n     *          the returned output stream. Advertising the value size up-front\n     *          guarantees that the value is encoded in one chunk, and avoids\n     *          intermediate chunk buffering.\n     * @throws IOException raised on errors performing I/O.\n     * @return DataOutputStream.\n     */\n    public DataOutputStream prepareAppendValue(int length) throws IOException {\n      if (state != State.END_KEY) {\n        throw new IllegalStateException(\n            \"Incorrect state to start a new value: \" + state.name());\n      }\n\n      DataOutputStream ret;\n\n      // unknown length\n      if (length < 0) {\n        if (valueBuffer == null) {\n          valueBuffer = new byte[getChunkBufferSize(conf)];\n        }\n        ret = new ValueRegister(new ChunkEncoder(blkAppender, valueBuffer));\n      } else {\n        ret =\n            new ValueRegister(new Chunk.SingleChunkEncoder(blkAppender, length));\n      }\n\n      state = State.IN_VALUE;\n      return ret;","sourceCodeStart":551,"sourceCodeEnd":587,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/io/file/tfile/TFile.java#L551-L587","documentation":"Thrown by TFile.Writer.prepareAppendValue(int) when the writer's state is not END_KEY, i.e. when the key stream from prepareAppendKey() has not been closed yet, or a previous value stream is still open. The state machine requires key-close before value-start (READY -> IN_KEY -> END_KEY -> IN_VALUE -> READY), and this check enforces it with IllegalStateException plus the current state name.","triggerScenarios":"Calling prepareAppendValue() immediately after prepareAppendKey() without closing the key stream; calling it twice for one record; calling it on a fresh writer where no key was appended.","commonSituations":"Writing key and value with nested streams and missing the inner key-stream close; copy-paste of a key-writing block that drops the close; early exits between key write and value start.","solutions":["Close the key stream before calling prepareAppendValue(), keeping each stream in its own try-with-resources block in the right order","Use writer.append(key, value) or writer.append(key, koff, klen, value, voff, vlen) to avoid manual state handling entirely","After any exception mid-record, close outstanding streams in finally, then close the writer; never resume appending"],"exampleFix":"// before\nDataOutputStream k = writer.prepareAppendKey(-1);\nk.write(key);\nDataOutputStream v = writer.prepareAppendValue(-1); // IllegalStateException: IN_KEY\n\n// after\ntry (DataOutputStream k = writer.prepareAppendKey(-1)) {\n  k.write(key);\n}\ntry (DataOutputStream v = writer.prepareAppendValue(-1)) {\n  v.write(value);\n}","handlingStrategy":"validation","validationCode":"// Always finish the key stream before starting the value stream\ntry (DataOutputStream k = writer.prepareAppendKey(keyLen)) {\n  k.write(keyBuf, 0, keyLen);\n} // state now END_KEY\ntry (DataOutputStream v = writer.prepareAppendValue(valLen)) {\n  v.write(valBuf, 0, valLen);\n} // state now READY","typeGuard":null,"tryCatchPattern":"catch (IllegalStateException e) {\n  // state in the message (IN_KEY / IN_VALUE / READY) tells you which stream was open;\n  // unwind: close inner streams, then writer.close()\n}","preventionTips":["Wrap each append stream in its own try-with-resources block in strict key-then-value order","Use the append() convenience overloads unless chunked value writing is required","Never call prepareAppendValue() twice for one record"],"tags":["hadoop","tfile","state-machine","writer"],"backgroundTag":"illegal-state-transition","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}