{"record":{"id":"9485e7f048be9ce0","repo":"hashicorp/nomad","slug":"error-restarting-allocation-q-s","errorCode":null,"errorMessage":"Error restarting allocation %q: %s","messagePattern":"Error restarting allocation %q: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"command/job_restart.go","lineNumber":870,"sourceCode":"\n// handleAlloc stops or restarts an allocation in-place. Blocks until the\n// allocation  is done restarting or the rescheduled allocation is running.\nfunc (c *JobRestartCommand) handleAlloc(alloc AllocationListStubWithJob) error {\n\tvar err error\n\tif c.reschedule {\n\t\t// Stopping an allocation triggers a reschedule.\n\t\terr = c.stopAlloc(alloc)\n\t} else {\n\t\terr = c.restartAlloc(alloc)\n\t}\n\tif err != nil {\n\t\tmsg := fmt.Sprintf(\"Error restarting allocation %q:\", limit(alloc.ID, c.length))\n\t\tif mErr, ok := err.(*multierror.Error); ok {\n\t\t\t// Unwrap the errors and prefix them with a common message to\n\t\t\t// prevent deep nesting of errors.\n\t\t\treturn multierror.Prefix(mErr, msg)\n\t\t}\n\t\treturn fmt.Errorf(\"%s %w\", msg, err)\n\t}\n\treturn nil\n}\n\n// restartAlloc restarts an allocation in place and blocks until the tasks are\n// done restarting.\nfunc (c *JobRestartCommand) restartAlloc(alloc AllocationListStubWithJob) error {\n\tshortAllocID := limit(alloc.ID, c.length)\n\n\tif c.allTasks {\n\t\tc.Ui.Output(fmt.Sprintf(\n\t\t\t\"    %s: Restarting all tasks in allocation %q for group %q\",\n\t\t\tformatTime(time.Now()),\n\t\t\tshortAllocID,\n\t\t\talloc.TaskGroup,\n\t\t))\n\n\t\treturn c.client.Allocations().RestartAllTasks(&api.Allocation{ID: alloc.ID}, nil)","sourceCodeStart":852,"sourceCodeEnd":888,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/command/job_restart.go#L852-L888","documentation":"handleAlloc wraps any failure from restarting an allocation (task-level restart errors, nested multierrors) behind 'Error restarting allocation <id>: ...', using multierror.Prefix to flatten nested errors for readability.","triggerScenarios":"api.Allocations().Restart fails or returns task errors while the job restart command restarts an alloc in place; errors are bubbled up prefixed with the (truncated) alloc ID.","commonSituations":"Nomad agent unreachable or client API errors; alloc already terminal/complete; task driver failures during in-place restart; ACL token lacking alloc-lifecycle permissions.","solutions":["Check nomad alloc status <alloc-id> and the agent logs for the root cause","Verify the ACL token has allocation lifecycle permissions (acl:write or alloc-lifecycle)","Confirm the Nomad agent address is reachable (NOMAD_ADDR) and healthy","Re-run the restart; transient API failures can be retried"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"alloc, _, err := client.Allocations().Info(allocID, nil)\nif err != nil || alloc.ClientStatus == \"complete\" || alloc.ClientStatus == \"failed\" {\n    return fmt.Errorf(\"alloc %s not restartable: clientStatus=%s\", allocID, alloc.ClientStatus)\n}","typeGuard":"func isRestartable(a *api.Allocation) bool {\n    return a != nil && a.ClientStatus == \"running\"\n}","tryCatchPattern":"if err := cmd.handleAlloc(alloc); err != nil {\n    var merr *multierror.Error\n    if errors.As(err, &merr) {\n        for _, e := range merr.Errors { log.Println(e) }\n    } else {\n        log.Printf(\"restart failed: %v\", err)\n    }\n}","preventionTips":["Confirm alloc is running before restarting","Keep the agent reachable and the ACL token valid","Check nomad alloc status for terminal allocs"],"tags":["nomad","api","allocation","restart"],"backgroundTag":"alloc-restart-failed","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"}