File status 21: Key sequence error

What it means

Status 21 is an invalid key condition. It only applies to indexed files, which in Enterprise COBOL on z/OS means a VSAM KSDS. QSAM and line-sequential files never return it.

IBM sets it in two cases. The first is a WRITE with ACCESS MODE SEQUENTIAL where the prime key isn't higher than the key of the record written before it. In sequential access, new records must arrive in ascending key order. The second is a REWRITE in sequential access where the prime key in the record area differs from the key of the record the last READ returned. REWRITE can't change the prime key.

The VSAM code behind the write case is register 15 = 8 with feedback code 12 (X'0C'), a record stored out of ascending key sequence. VSAM notes that the same code can also mean a duplicate key in that situation. The REWRITE case is a COBOL rule about the key in the record area, so look at the key fields rather than a VSAM code. The INVALID KEY phrase, if coded, runs after the status is set.

Common causes

• A KSDS is loaded with ACCESS MODE SEQUENTIAL from input that isn't sorted on the key, or is sorted on the wrong field.
• The input was sorted in ASCII order on another platform. In EBCDIC, digits sort after letters, so the order changes on z/OS.
• OPEN EXTEND adds records whose first key isn't higher than the highest key already in the file.
• The program changes a key field between READ and REWRITE, for example by moving a whole new layout or running INITIALIZE on the record area.
• The sorted input holds the same key twice, which VSAM can report the same way as an out-of-sequence key.

How to find the problem

1. DISPLAY the key of the record that got 21 and the key of the record written before it. The new key will be lower or equal.
2. Check the sort step that built the input. Compare the SORT FIELDS position, length and format with the cluster's RKP and KEYLEN from IDCAMS LISTCAT ALL.
3. If data-name-8 is coded on the FILE STATUS clause, display it. Return code 8 with feedback 12 confirms a sequence error on a write.
4. For a REWRITE, display the key in the record area just before the REWRITE and compare it with the key the READ returned.

How to fix it

• Sort the input on exactly the prime key, with the same offset, length and EBCDIC sequence, before a sequential load.
• If the input can't be sorted, use ACCESS MODE RANDOM or DYNAMIC. A random WRITE accepts keys in any order.
• Never change the prime key with REWRITE. To change a key, DELETE the old record and WRITE a new one.
• Remove or merge duplicate keys before the load, or the job stops at the first one.

Last reviewed 2026-10-18 by the WND Software team. Written in our own words. For the full reference, check IBM’s Enterprise COBOL documentation for your release.