eclipse-vertx/vert.x · error · IllegalStateException

Not a streaming upload

Error message

Not a streaming upload

What it means

HttpServerFileUploadImpl.cancelStreamToFileSystem() cancels an in-progress streaming upload to disk. The upload only has an internal pipe when it was started with toFilesystem streaming (streamingToFileSync); if the upload was buffered in memory or no streaming-to-file was ever started, pipe is null and this IllegalStateException is thrown because there is nothing to cancel.

Source

Thrown at vertx-core/src/main/java/io/vertx/core/http/impl/HttpServerFileUploadImpl.java:203

          if (!cancelled) {
            file = f;
            return context.succeededFuture();
          }
          fs.delete(filename);
          return context.failedFuture("Streaming aborted");
        }
      }, err -> {
        fs.delete(filename);
        return context.failedFuture(err);
      });
    });
  }

  @Override
  public boolean cancelStreamToFileSystem() {
    synchronized (this) {
      if (pipe == null) {
        throw new IllegalStateException("Not a streaming upload");
      }
      if (file != null) {
        return false;
      }
      cancelled = true;
    }
    pipe.close();
    return true;
  }

  @Override
  public synchronized boolean isSizeAvailable() {
    return !lazyCalculateSize;
  }

  @Override
  public synchronized AsyncFile file() {
    return file;

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Only call cancelStreamToFileSystem() on uploads for which a streaming file target was requested (e.g. upload.streamToFileSystem(...) was called and is still in progress)
2. Check the upload state before canceling; if it is not streaming, simply discard it (e.g. stream to null/buffer) instead
3. Wrap the cancel call in a try/catch for IllegalStateException when upload streaming mode is not known in advance

Example fix

// before
upload.cancelStreamToFileSystem(); // throws if upload is not streaming to a file

// after
try {
  boolean cancelled = upload.cancelStreamToFileSystem();
} catch (IllegalStateException e) {
  // upload is not a streaming-to-file upload; discard it another way
  upload.handler(buf -> {});
  upload.endHandler(v -> {});
}

// Track whether you started streaming to a file
boolean streamingToFile = startedStreamToFileSystem;
if (streamingToFile && upload.cancelStreamToFileSystem() == false) {
  // file already written; cancel too late
}

try {
  upload.cancelStreamToFileSystem();
} catch (IllegalStateException e) {
  // not a streaming upload; discard via handlers instead
}

When it happens

Trigger: Calling cancelStreamToFileSystem() on an upload whose body is being buffered in memory (no streaming to a file was initiated), or after the streaming upload already completed/never started.

Common situations: Applications that call cancel on every upload in an uploadHandler regardless of whether the upload is streaming to a file; canceling after the upload finished so file is already set returns false instead (no exception), but canceling a non-streaming upload throws.

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

Related errors

• Request has already been read
• Response head already sent
• Response has already been written
• size must be > 0
• maxExecuteTime must be > 0

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