What causes "missing AllocID" in hashicorp/nomad?

Set AllocID on the FS streaming request before opening the stream.

missing AllocID

Error message

missing AllocID

What it means

Inside the filesystem streaming endpoint (used by Stream/Log/Read paths), args.AllocID is validated after ACL checks. As this is a streaming RPC, the "missing AllocID" error is delivered over the stream via handleStreamResultError with code 400 and the stream is closed. The request had no allocation to stream file contents from.

Source

Thrown at nomad/client_fs_endpoint.go:254

	}

	authErr := f.srv.Authenticate(nil, &args)

	// Check if we need to forward to a different region
	if r := args.RequestRegion(); r != f.srv.Region() {
		forwardRegionStreamingRpc(f.srv, conn, encoder, &args, "FileSystem.Stream",
			args.AllocID, &args.QueryOptions)
		return
	}
	f.srv.MeasureRPCRate("file_system", structs.RateMetricRead, &args)
	if authErr != nil {
		handleStreamResultError(structs.ErrPermissionDenied, nil, encoder)
		return
	}

	// Verify the arguments.
	if args.AllocID == "" {
		handleStreamResultError(errors.New("missing AllocID"), new(int64(400)), encoder)
		return
	}

	// Retrieve the allocation
	snap, err := f.srv.State().Snapshot()
	if err != nil {
		handleStreamResultError(err, nil, encoder)
		return
	}

	alloc, err := getAlloc(snap, args.AllocID)
	if structs.IsErrUnknownAllocation(err) {
		handleStreamResultError(structs.NewErrUnknownAllocation(args.AllocID), new(int64(404)), encoder)
		return
	}
	if err != nil {
		handleStreamResultError(err, nil, encoder)
		return

View on GitHub (pinned to 482b49bf1a)

Solutions

Set AllocID on the FS streaming request before opening the stream.
Resolve and cache the alloc ID before each (re)connection attempt.
Handle the streamed 400 error frame in your streaming client.
Validate AllocID non-empty before dialing the stream.

Example fix

// before
req := structs.FsStreamRequest{Path: "logs/app.log", Follow: true}
fs.Stream(ctx, req, ...)
// after
req := structs.FsStreamRequest{AllocID: alloc.ID, Path: "logs/app.log", Follow: true}
fs.Stream(ctx, req, ...)

Defensive patterns

Strategy: validation

Validate before calling

if allocID == "" {
    return fmt.Errorf("FS stream requires a non-empty AllocID")
}
// proceed to open streaming FS RPC

Type guard

func streamRequestValid(req *structs.FsStreamRequest) bool {
    return req != nil && req.AllocID != "" && req.Origin != ""
}

Try / catch

// streaming RPC: consume error frames
for {
    frame, err := recv(stream)
    if err != nil { return err }
    if frame.IsError {
        return fmt.Errorf("fs stream failed (code %d): %s", frame.Error.Code, frame.Error.Message)
    }
    // process data frames
}

Prevention

Set AllocID before opening any FS streaming call (Stream/Read/Logs).
Re-validate the alloc ID on every stream reconnect — reconnection code often drops it.
Treat 400 error frames from the stream as fatal configuration issues, not retryable ones.

When it happens

Trigger: Opening a StreamingFsOperation (or StreamFrames-based FS call) with the request's AllocID left as "".

Common situations: Custom log streaming clients (like nomad log tailers) failing to set AllocID; CLI flag defaults leaving the ID empty; reconnection logic that drops the alloc ID between reconnect attempts.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

AI-assisted analysis of hashicorp/nomad@482b49bf1a (2026-09-04). Data as JSON: /api/errors/20a7b87ae50d0c82. Report an issue: GitHub.