eclipse-vertx/vert.x · error · IllegalStateException

File handle is closed

Error message

File handle is closed

What it means

Lifecycle guard in AsyncFileImpl: an operation was attempted on an AsyncFile whose underlying file handle has already been closed (the internal 'closed' flag is set). Every read/write/flush path funnels through checkClosed(), so any post-close use fails fast with this IllegalStateException instead of touching a dead handle.

Source

Thrown at vertx-core/src/main/java/io/vertx/core/file/impl/AsyncFileImpl.java:513

        } else {
          // It's been fully written
          done();
        }
      }

      public void failed(Throwable t, Object attachment) {
        promise.fail(t);
      }
    });
  }

  private void check() {
    checkClosed();
  }

  private void checkClosed() {
    if (closed) {
      throw new IllegalStateException("File handle is closed");
    }
  }

  private void checkContext() {
    if (!vertx.getContext().equals(context)) {
      throw new IllegalStateException("AsyncFile must only be used in the context that created it, expected: "
          + context + " actual " + vertx.getContext());
    }
  }

  private void doClose(Promise<Void> handler) {
    context.<Void>executeBlockingInternal(() -> {
      ch.close();
      return null;
    }).onComplete(handler);
  }

  private synchronized void closeInternal(Promise<Void> handler) {

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Track closure (e.g. via the close future) and skip operations after close
2. Sequence operations so close() happens after all reads/writes complete

When it happens

Trigger: Thrown at vertx-core/src/main/java/io/vertx/core/file/impl/AsyncFileImpl.java:513 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of eclipse-vertx/vert.x@fb308bd8c3 (2026-09-06). Data as JSON: /api/errors/0f32e2756491e11a. Report an issue: GitHub.