github/copilot-sdk · critical · IOException

Failed to write a frame to the in-process runtime…

Error message

Failed to write a frame to the in-process runtime connection.

What it means

FfiOutputStream.write throws this IOException when the native binding connectionWrite(id, payload, length) returns false — the frame was not delivered to the in-process runtime. The Java side had a valid connection id, but the native layer refused or failed the write (e.g., broken pipe into the runtime, runtime shutting down, backpressure/serialization failure).

Solutions

1. Check the runtime's health/liveness before writing; detect crash and reconnect/restart the host
2. Retry the write once on transient failure, then fail the stream if the runtime is down
3. Catch this IOException and stop the producer rather than looping on a dead connection
4. Inspect native-side logs to confirm whether the runtime rejected the frame or the connection reset

Example fix

// before
stream.write(frame); // throws when runtime died
// after
try {
    stream.write(frame);
} catch (IOException e) {
    if (String.valueOf(e.getMessage()).contains("Failed to write a frame")) {
        host.restart();
    } else {
        throw e;
    }
}

// health-check the runtime before writing
if (!host.isRuntimeAlive()) { host.restart(); }

try {
    stream.write(data);
} catch (IOException e) {
    if (String.valueOf(e.getMessage()).contains("Failed to write a frame")) {
        host.restart();
        // single retry, then give up
    } else throw e;
}

When it happens

Trigger: connectionWrite returning false during a write after (or during) runtime shutdown, a crashed embedded runtime, or a native-side connection reset — even though the Java-side connectionId is nonzero and closing is false.

Common situations: Embedded runtime process dying mid-stream while the Java host keeps writing; oversized frames the native layer rejects; racing close on the native side with in-flight writes from multiple threads (the operationLock only serializes Java-side calls).

Related errors

• Invalid off/len for buffer of length
• The in-process runtime connection is closed.
• copilot_runtime_host_start failed (library '').
• copilot_runtime_connection_open failed.
• copilot_runtime_host_start failed

AI-assisted analysis of github/copilot-sdk@cd8cf15dc3 (2026-09-09). Data as JSON: /api/errors/7b1130fefdef0408. Report an issue: GitHub.

Appendix: source

Thrown at java/sdk/src/main/java/com/github/copilot/ffi/FfiOutputStream.java:57

            throw new IndexOutOfBoundsException("Invalid off/len for buffer of length " + b.length);
        }
        if (len == 0) {
            return;
        }

        operationLock.lock();
        try {
            if (closing.get()) {
                throw new IOException("The in-process runtime connection is closed.");
            }
            int id = connectionId.get();
            if (id == 0) {
                throw new IOException("The in-process runtime connection is closed.");
            }

            byte[] payload = (off == 0 && len == b.length) ? b : Arrays.copyOfRange(b, off, off + len);
            if (!nativeBinding.connectionWrite(id, payload, payload.length)) {
                throw new IOException("Failed to write a frame to the in-process runtime connection.");
            }
        } finally {
            operationLock.unlock();
        }
    }
}

View on GitHub (pinned to cd8cf15dc3)