karatelabs/karate · error · RuntimeException

failed to read item at index

Error message

failed to read item at index ${index}

What it means

DiskBackedList.get() wraps any IOException raised while seeking/reading the backing temp file in a RuntimeException with this message, chaining the original IOException as cause. It means the on-disk serialized line for that index could not be read.

Solutions

1. Inspect the chained IOException cause for the root reason
2. Keep the DiskBackedList short-lived and close it deterministically after use
3. Configure java.io.tmpdir to a stable location not subject to aggressive cleanup
4. Ensure temp files are not deleted externally while the list is alive

Example fix

// before
DiskBackedList list = new DiskBackedList(items, new File("/tmp/cache"));
// after
File dir = new File(System.getProperty("java.io.tmpdir")); // stable, app-managed
DiskBackedList list = new DiskBackedList(items, dir);

File temp = backingFileOf(list);
if (temp == null || !temp.exists() || !temp.canRead()) throw new IOException("backing file unavailable: " + temp);

boolean readable(File f) { return f != null && f.isFile() && f.canRead(); }

try { return list.get(i); } catch (RuntimeException e) { if (e.getCause() instanceof IOException) { log.error("disk read failed for index " + i, e.getCause()); } throw e; }

When it happens

Trigger: The temp file was deleted or truncated after list creation (e.g. temp dir cleanup); disk I/O error; file descriptor exhausted; underlying filesystem became unavailable mid-read.

Common situations: Long-lived lists whose temp files got cleaned by OS/tmp reapers; containers with small or volatile /tmp; running out of file handles under load.

Understand the failure class

Background: "failed to read file", EACCES, ENOENT and "could not read <path>" errors: when a program can't read a file from disk — this error's family across 49 libraries.

Related errors

• failed to read next line
• Failed to read bytes from
• temp file not found
• Failed to read text from
• xmlPath failed for path

AI-assisted analysis of karatelabs/karate@a22eb90246 (2026-09-12). Data as JSON: /api/errors/12ba8531d9e5a8bc. Report an issue: GitHub.

Appendix: source

Thrown at karate-core/src/main/java/io/karatelabs/match/DiskBackedList.java:193

    @Override
    public Object get(int index) {
        if (closed) {
            throw new IllegalStateException("store has been closed");
        }
        if (index < 0 || index >= size) {
            throw new IndexOutOfBoundsException("index: " + index + ", size: " + size);
        }
        try {
            if (raf == null) {
                raf = new RandomAccessFile(tempFile, "r");
            }
            long offset = lineOffsets.get(index);
            raf.seek(offset);
            String line = raf.readLine();
            return deserializeItem(line);
        } catch (IOException e) {
            throw new RuntimeException("failed to read item at index " + index, e);
        }
    }

    @Override
    public Iterator<Object> iterator() {
        if (closed) {
            throw new IllegalStateException("store has been closed");
        }
        return new DiskBackedIterator();
    }

    @Override
    public void close() {
        if (closed) {
            return;
        }
        closed = true;
        if (raf != null) {

View on GitHub (pinned to a22eb90246)