{"record":{"id":"cb74c6a335f95c10","repo":"hashicorp/nomad","slug":"must-provide-a-valid-alloc-id","errorCode":null,"errorMessage":"must provide a valid alloc id","messagePattern":"must provide a valid alloc id","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"client/fs_endpoint.go","lineNumber":33,"sourceCode":"\t\"sort\"\n\t\"strconv\"\n\t\"strings\"\n\t\"syscall\"\n\t\"time\"\n\n\tmetrics \"github.com/hashicorp/go-metrics/compat\"\n\t\"github.com/hashicorp/go-msgpack/v2/codec\"\n\t\"github.com/hpcloud/tail/watch\"\n\n\t\"github.com/hashicorp/nomad/acl\"\n\t\"github.com/hashicorp/nomad/client/allocdir\"\n\tsframer \"github.com/hashicorp/nomad/client/lib/streamframer\"\n\tcstructs \"github.com/hashicorp/nomad/client/structs\"\n\t\"github.com/hashicorp/nomad/nomad/structs\"\n)\n\nvar (\n\tallocIDNotPresentErr = fmt.Errorf(\"must provide a valid alloc id\")\n\tpathNotPresentErr    = fmt.Errorf(\"must provide a file path\")\n\ttaskNotPresentErr    = fmt.Errorf(\"must provide task name\")\n\tlogTypeNotPresentErr = fmt.Errorf(\"must provide log type (stdout/stderr)\")\n\tinvalidOrigin        = fmt.Errorf(\"origin must be start or end\")\n)\n\nconst (\n\t// streamFramesBuffer is the number of stream frames that will be buffered\n\t// before back pressure is applied on the stream framer.\n\tstreamFramesBuffer = 32\n\n\t// streamFrameSize is the maximum number of bytes to send in a single frame\n\tstreamFrameSize = 64 * 1024\n\n\t// streamHeartbeatRate is the rate at which a heartbeat will occur to detect\n\t// a closed connection without sending any additional data\n\tstreamHeartbeatRate = 1 * time.Second\n","sourceCodeStart":15,"sourceCodeEnd":51,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/client/fs_endpoint.go#L15-L51","documentation":"allocIDNotPresentErr is a sentinel error in the client's filesystem endpoint signaling that a request arrived with an empty AllocID. Every FS operation (logs, stream, stat, list, exec) requires an allocation ID to route to the correct alloc runner. It is returned with HTTP 400 Bad Request.","triggerScenarios":"Calling Logs, Stream, execImpl, DirectoryListRequest, FileStatRequest, or FileReadAtRequest with req.AllocID == \"\" — e.g. an API client omitting the ?alloc_id= parameter or building a structs request with a zero-value AllocID.","commonSituations":"Custom tooling calling /v1/client/fs/... endpoints without the alloc ID query param; a caller using an uninitialized struct; UI/API layer dropping the alloc ID during request forwarding.","solutions":["Populate AllocID (or the alloc_id query parameter) with a valid allocation ID from nomad job status <job>","Verify the HTTP request actually includes the parameter and it isn't stripped by a proxy/template","Confirm the allocation ID string is non-empty before invoking the client API in your code"],"exampleFix":"// before\nreq := &cstructs.FsStreamRequest{Path: \"/logs/foo.log\", Origin: \"start\"}\n// after\nreq := &cstructs.FsStreamRequest{AllocID: alloc.ID, Path: \"/logs/foo.log\", Origin: \"start\"}","handlingStrategy":"validation","validationCode":"if allocID == \"\" {\n    return nil, fmt.Errorf(\"allocID is required: run 'nomad job status <job>' to obtain one\")\n}","typeGuard":"func hasAllocID(req *cstructs.FsStreamRequest) bool {\n    return req != nil && req.AllocID != \"\"\n}","tryCatchPattern":"resp, err := client.FS().Logs(ctx, alloc, \"web\", false, \"stdout\", \"start\", 0, false, nil)\nif err != nil && strings.Contains(err.Error(), \"must provide a valid alloc id\") {\n    log.Printf(\"request rejected: alloc ID missing — re-resolve allocation: %v\", err)\n    alloc = resolveAlloc()\n    return client.FS().Logs(ctx, alloc, \"web\", false, \"stdout\", \"start\", 0, false, nil)\n}","preventionTips":["Always fetch the allocation object via the API and pass alloc.ID — never type IDs by hand","Assert AllocID != \"\" in request-builder helpers","When forwarding HTTP, preserve all query parameters (proxy configs can strip alloc_id)","Add a unit test asserting request builders populate AllocID"],"tags":["api","validation","filesystem"],"backgroundTag":"missing-required-argument","analyzedSha":"482b49bf1aec006f089bcfc7e632d8f6ac303e5e","analyzedAt":"2026-09-04T07:54:14.808Z","contentChangedAt":"2026-09-04T07:54:14.808Z","schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}