{"record":{"id":"8a165f73440a3125","repo":"hashicorp/nomad","slug":"must-provide-a-file-path","errorCode":null,"errorMessage":"must provide a file path","messagePattern":"must provide a file path","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"client/fs_endpoint.go","lineNumber":34,"sourceCode":"\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\n\t// streamBatchWindow is the window in which file content is batched before","sourceCodeStart":16,"sourceCodeEnd":52,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/client/fs_endpoint.go#L16-L52","documentation":"pathNotPresentErr is a sentinel error returned by the client FS stream endpoint when the request's Path field is empty. Streaming a file requires an absolute path inside the allocation. Returned to the stream encoder with HTTP 400 Bad Request.","triggerScenarios":"Calling the Stream (fs stream) endpoint with req.Path == \"\" — e.g. GET /v1/client/fs/stream/<alloc> without the ?path= query parameter.","commonSituations":"API consumers following the logs endpoint pattern but forgetting that stream requires an explicit file path; automation omitting the path after URL-encoding bugs drop it; empty variable interpolated into the path param.","solutions":["Supply the path query parameter with an absolute file path inside the allocation (e.g. /alloc/logs/app.stdout.0)","If building the request in code, set req.Path explicitly before calling Stream","Check URL construction for dropped/empty query parameters (log the final URL)"],"exampleFix":"// before\nGET /v1/client/fs/stream/<alloc_id>?origin=start\n// after\nGET /v1/client/fs/stream/<alloc_id>?path=/alloc/logs/app.stdout.0&origin=start","handlingStrategy":"validation","validationCode":"if path == \"\" {\n    return nil, fmt.Errorf(\"path is required for streaming; e.g. /alloc/logs/<task>.stdout.0\")\n}","typeGuard":"func hasPath(req *cstructs.FsStreamRequest) bool {\n    return req != nil && req.Path != \"\"\n}","tryCatchPattern":"err := streamFile(ctx, alloc, path)\nif err != nil && strings.Contains(err.Error(), \"must provide a file path\") {\n    log.Printf(\"no path supplied, defaulting to /alloc/logs/%s.stdout.0\", task)\n    return streamFile(ctx, alloc, fmt.Sprintf(\"/alloc/logs/%s.stdout.0\", task))\n}","preventionTips":["Build file paths from the well-known alloc layout (/alloc/, /local/, task dirs) instead of free text","Log the fully constructed URL before issuing stream requests","Guard template variables so an empty variable cannot silently empty the path param"],"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"}