{"record":{"id":"e90de2d03f64eab6","repo":"hashicorp/nomad","slug":"missing-allocation-id","errorCode":null,"errorMessage":"missing allocation ID","messagePattern":"missing allocation ID","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"nomad/client_fs_endpoint.go","lineNumber":125,"sourceCode":"\t// the Node registration and the cost is fairly high for adding another hope\n\t// in the forwarding chain.\n\targs.QueryOptions.AllowStale = true\n\n\tauthErr := f.srv.Authenticate(nil, args)\n\n\t// Potentially forward to a different region.\n\tif done, err := f.srv.forward(\"FileSystem.List\", args, args, reply); done {\n\t\treturn err\n\t}\n\tf.srv.MeasureRPCRate(\"file_system\", structs.RateMetricList, args)\n\tif authErr != nil {\n\t\treturn structs.ErrPermissionDenied\n\t}\n\tdefer metrics.MeasureSince([]string{\"nomad\", \"file_system\", \"list\"}, time.Now())\n\n\t// Verify the arguments.\n\tif args.AllocID == \"\" {\n\t\treturn errors.New(\"missing allocation ID\")\n\t}\n\n\t// Lookup the allocation\n\tsnap, err := f.srv.State().Snapshot()\n\tif err != nil {\n\t\treturn err\n\t}\n\n\talloc, err := getAlloc(snap, args.AllocID)\n\tif err != nil {\n\t\treturn err\n\t}\n\n\t// Check namespace filesystem read permissions\n\tallowNsOp := acl.NamespaceValidator(acl.NamespaceCapabilityReadFS)\n\taclObj, err := f.srv.ResolveACL(args)\n\tif err != nil {\n\t\treturn err","sourceCodeStart":107,"sourceCodeEnd":143,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/nomad/client_fs_endpoint.go#L107-L143","documentation":"The FileSystem.List RPC (reading an allocation's sandbox directory listing) validates args.AllocID after ACL checks. An empty AllocID cannot identify which allocation's filesystem to list, so \"missing allocation ID\" is returned before the state lookup. Note this variant uses the wording \"missing allocation ID\" rather than \"missing AllocID\".","triggerScenarios":"Calling ClientFileSystem.List with structs.AllocListRequest where AllocID is \"\".","commonSituations":"Custom log/file browsing tools against the FS API with an empty alloc ID; CLI built on the FS endpoints where a positional arg was omitted; zero-valued request structs in automation.","solutions":["Set args.AllocID to the allocation UUID before calling List.","Obtain the alloc ID from the job allocations API or `nomad job allocs`.","Validate AllocID non-empty before the RPC call."],"exampleFix":"// before\nargs := structs.AllocListRequest{Path: \"/logs\"}\nerr := fs.List(args, &reply)\n// after\nargs := structs.AllocListRequest{AllocID: alloc.ID, Path: \"/logs\"}\nerr := fs.List(args, &reply)","handlingStrategy":"validation","validationCode":"if allocID == \"\" {\n    return fmt.Errorf(\"FS List requires a non-empty AllocID\")\n}","typeGuard":"func canListFS(args *structs.AllocListRequest) bool {\n    return args != nil && args.AllocID != \"\" && args.Path != \"\"\n}","tryCatchPattern":null,"preventionTips":["Always set AllocID when building FS requests.","In CLIs, require the alloc ID argument and error out before dialing if empty.","Cache alloc IDs from lookups instead of relying on ambient variables."],"tags":["nomad","rpc","argument-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"}