{"record":{"id":"a7c3d54500539b04","repo":"apache/hadoop","slug":"incorrect-state-to-start-a-meta-block-state","errorCode":null,"errorMessage":"Incorrect state to start a Meta Block: {state}","messagePattern":"Incorrect state to start a Meta Block: (.+?)","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":611,"sourceCode":"     * active. No more key-value insertion is allowed after a meta data block\n     * has been added to TFile.\n     * \n     * @param name\n     *          Name of the meta block.\n     * @param compressName\n     *          Name of the compression algorithm to be used. Must be one of the\n     *          strings returned by\n     *          {@link TFile#getSupportedCompressionAlgorithms()}.\n     * @return A DataOutputStream that can be used to write Meta Block data.\n     *         Closing the stream would signal the ending of the block.\n     * @throws IOException raised on errors performing I/O.\n     * @throws MetaBlockAlreadyExists\n     *           the Meta Block with the same name already exists.\n     */\n    public DataOutputStream prepareMetaBlock(String name, String compressName)\n        throws IOException, MetaBlockAlreadyExists {\n      if (state != State.READY) {\n        throw new IllegalStateException(\n            \"Incorrect state to start a Meta Block: \" + state.name());\n      }\n\n      finishDataBlock(true);\n      DataOutputStream outputStream =\n          writerBCF.prepareMetaBlock(name, compressName);\n      return outputStream;\n    }\n\n    /**\n     * Obtain an output stream for creating a meta block. This function may not\n     * be called when there is a key append stream or value append stream\n     * active. No more key-value insertion is allowed after a meta data block\n     * has been added to TFile. Data will be compressed using the default\n     * compressor as defined in Writer's constructor.\n     * \n     * @param name\n     *          Name of the meta block.","sourceCodeStart":593,"sourceCodeEnd":629,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/io/file/tfile/TFile.java#L593-L629","documentation":"Thrown by TFile.Writer.prepareMetaBlock(String name, String compressName) when the writer is not in the READY state, i.e. when a key or value append stream is still open. Meta blocks (named auxiliary blocks such as TFile's own metadata) can only be written between records, not in the middle of one. IllegalStateException carries the offending state name.","triggerScenarios":"Calling prepareMetaBlock(name, compressName) while a stream from prepareAppendKey() or prepareAppendValue() is unclosed; interleaving meta block writes into the middle of a key-value insertion sequence.","commonSituations":"Code that writes a meta block on a timer or callback without coordinating with the record-writing loop; exception in the record loop leaving a stream open, followed by a finally-block meta write; refactored writers that emit meta blocks after N records but forget to finish the current record first.","solutions":["Finish the in-flight record (close key and value streams) before calling prepareMetaBlock","Structure writes as: all key-value appends, then meta blocks, then close(); this matches the intended TFile layout","Close meta block streams promptly too, so the writer returns to READY for the next data record"],"exampleFix":"// before\nDataOutputStream k = writer.prepareAppendKey(-1);\nk.write(key);\nDataOutputStream meta = writer.prepareMetaBlock(\"stats\", \"gz\"); // IllegalStateException\n\n// after\ntry (DataOutputStream k = writer.prepareAppendKey(-1)) {\n  k.write(key);\n}\nDataOutputStream meta = writer.prepareMetaBlock(\"stats\", \"gz\"); // OK: READY","handlingStrategy":"validation","validationCode":"// Only write meta blocks between records: finish data first, then meta\nfor (Record r : records) {\n  writer.append(r.key(), r.value());\n}\ntry (DataOutputStream meta = writer.prepareMetaBlock(\"stats\", TFile.COMPRESSION_GZ)) {\n  meta.write(statsBytes);\n}\nwriter.close();","typeGuard":null,"tryCatchPattern":"catch (IllegalStateException e) {\n  // a key/value stream was open; close it, then retry the meta block on a consistent writer only if no bytes were mid-record\n}","preventionTips":["Write all key-value pairs first, then meta blocks, then close: this ordering can never hit the check","Do not emit meta blocks from callbacks or timers that can fire mid-record","Close each meta block stream immediately so the writer returns to READY"],"tags":["hadoop","tfile","state-machine","meta-block","writer"],"backgroundTag":"illegal-state-transition","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-23T01:17:44.959Z"}