{"record":{"id":"4e44ca2480f38812","repo":"hashicorp/nomad","slug":"controller-publish-v","errorCode":null,"errorMessage":"controller publish: %v","messagePattern":"controller publish: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"nomad/csi_endpoint.go","lineNumber":505,"sourceCode":"\t\tif alloc == nil {\n\t\t\treturn fmt.Errorf(\"%s: %s\",\n\t\t\t\tstructs.ErrUnknownAllocationPrefix, args.AllocationID)\n\t\t}\n\t\targs.NodeID = alloc.NodeID\n\t}\n\n\t_, index, err := v.srv.raftApply(structs.CSIVolumeClaimRequestType, args)\n\tif err != nil {\n\t\tv.logger.Error(\"csi raft apply failed\", \"error\", err, \"method\", \"claim\")\n\t\treturn err\n\t}\n\n\tif isNewClaim {\n\t\t// if this is a new claim, add a Volume and PublishContext from the\n\t\t// controller (if any) to the reply\n\t\terr = v.controllerPublishVolume(args, reply)\n\t\tif err != nil {\n\t\t\treturn fmt.Errorf(\"controller publish: %v\", err)\n\t\t}\n\t}\n\n\treply.Index = index\n\tv.srv.setQueryMeta(&reply.QueryMeta)\n\treturn nil\n}\n\nfunc csiVolumeMountOptions(c *structs.CSIMountOptions) *cstructs.CSIVolumeMountOptions {\n\tif c == nil {\n\t\treturn nil\n\t}\n\n\treturn &cstructs.CSIVolumeMountOptions{\n\t\tFilesystem: c.FSType,\n\t\tMountFlags: c.MountFlags,\n\t}\n}","sourceCodeStart":487,"sourceCodeEnd":523,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/nomad/csi_endpoint.go#L487-L523","documentation":"For a new volume claim, Claim calls controllerPublishVolume to have the CSI controller publish the volume to the node. Any error from that controller RPC is wrapped as 'controller publish: %v', so the root cause is in the nested error (plugin errors, node issues, RPC failures).","triggerScenarios":"A new claim (not GC) on a volume whose plugin has a controller, and the controller publish RPC fails — e.g. controller unreachable, volume not yet created at the provider, or node not viable.","commonSituations":"CSI controller job down or not scheduled; external storage backend errors (volume doesn't exist, capacity exceeded); network partition between Nomad client and controller; stale plugin registration pointing to a dead node.","solutions":["Read the wrapped inner error to find the controller failure cause and fix that (e.g. restart controller job, fix storage backend)","Verify plugin/controller health with nomad plugin status <plugin>","Check that the volume exists at the provider and the target node is healthy, then retry the claim"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"p, _ := client.CSIPlugins().Get(pluginID, nil)\nif p == nil || p.ControllersHealthy < 1 {\n    return errors.New(\"controller unavailable for publish\")\n}","typeGuard":null,"tryCatchPattern":"if err := claim(); err != nil {\n    if wrapped := errors.Unwrap(err); wrapped != nil {\n        // inspect controller publish cause and retry with backoff\n    }\n}","preventionTips":["Monitor controller health before claiming volumes","Ensure the volume exists at the storage provider","Retry claims with backoff for transient controller RPC failures","Keep plugin jobs healthy and reachable from clients"],"tags":["csi","controller","publish"],"backgroundTag":"csi-controller-publish-failed","analyzedSha":"482b49bf1aec006f089bcfc7e632d8f6ac303e5e","analyzedAt":"2026-09-04T07:54:14.808Z","contentChangedAt":"2026-09-04T07:54:14.808Z","schemaVersion":2},"datasetVersion":"2026-09-08T15:18:49.778Z"}