{"record":{"id":"45d9278a6affa42b","repo":"docker/cli","slug":"replicas-can-only-be-used-with-replicated-or-repli-45d927","errorCode":null,"errorMessage":"replicas can only be used with replicated or replicated-job mode","messagePattern":"replicas can only be used with replicated or replicated-job mode","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cli/compose/convert/service.go","lineNumber":637,"sourceCode":"\tfor name, value := range source {\n\t\tswitch value {\n\t\tcase nil:\n\t\t\toutput = append(output, name)\n\t\tdefault:\n\t\t\toutput = append(output, name+\"=\"+*value)\n\t\t}\n\t}\n\tsort.Strings(output)\n\treturn output\n}\n\nfunc convertDeployMode(mode string, replicas *uint64) (swarm.ServiceMode, error) {\n\tserviceMode := swarm.ServiceMode{}\n\n\tswitch mode {\n\tcase \"global-job\":\n\t\tif replicas != nil {\n\t\t\treturn serviceMode, errors.New(\"replicas can only be used with replicated or replicated-job mode\")\n\t\t}\n\t\tserviceMode.GlobalJob = &swarm.GlobalJob{}\n\tcase \"global\":\n\t\tif replicas != nil {\n\t\t\treturn serviceMode, errors.New(\"replicas can only be used with replicated or replicated-job mode\")\n\t\t}\n\t\tserviceMode.Global = &swarm.GlobalService{}\n\tcase \"replicated-job\":\n\t\tserviceMode.ReplicatedJob = &swarm.ReplicatedJob{\n\t\t\tMaxConcurrent:    replicas,\n\t\t\tTotalCompletions: replicas,\n\t\t}\n\tcase \"replicated\", \"\":\n\t\tserviceMode.Replicated = &swarm.ReplicatedService{Replicas: replicas}\n\tdefault:\n\t\treturn serviceMode, fmt.Errorf(\"unknown mode: %s\", mode)\n\t}\n\treturn serviceMode, nil","sourceCodeStart":619,"sourceCodeEnd":655,"githubUrl":"https://github.com/docker/cli/blob/4f84911bfe8811e9b028e4b1fee8e7510be79387/cli/compose/convert/service.go#L619-L655","documentation":"Returned by convertDeployMode (service.go:636-637) when deploy.mode is 'global-job' AND deploy.replicas is also set. Global-job mode runs exactly one task per node, so a replica count is meaningless and the converter rejects it. Only 'replicated' and 'replicated-job' modes honor replicas.","triggerScenarios":"In docker-compose.yml for a Swarm-deployed service: deploy: { mode: global-job, replicas: 3 }. The switch case at line 635 sees mode 'global-job' with a non-nil replicas pointer and returns the error.","commonSituations":"Copy-pasting a deploy block from a replicated service into a global-job service. Misunderstanding global-job semantics (one task per node). Templating that always emits replicas.","solutions":["Remove 'replicas:' when using mode: global-job.","If you need a fixed task count, switch mode to 'replicated-job' (or 'replicated') and keep replicas.","Validate with 'docker compose config' before deploying."],"exampleFix":"# before\ndeploy:\n  mode: global-job\n  replicas: 3\n\n# after\ndeploy:\n  mode: global-job","handlingStrategy":"validation","validationCode":"// Validate deploy mode/replicas consistency for Swarm conversion.\nfunc validateDeployMode(mode string, replicas *uint64) error {\n    if (mode == \"global\" || mode == \"global-job\") && replicas != nil {\n        return errors.New(\"replicas can only be used with replicated or replicated-job mode\")\n    }\n    return nil\n}","typeGuard":"// deployModeAllowsReplicas reports whether 'mode' honors a replicas count.\nfunc deployModeAllowsReplicas(mode string) bool {\n    switch mode {\n    case \"replicated\", \"replicated-job\", \"\":\n        return true\n    default: // global, global-job\n        return false\n    }\n}","tryCatchPattern":null,"preventionTips":["Drop 'replicas' whenever setting mode: global or global-job.","Templating systems should omit replicas for global modes instead of defaulting it.","Validate with 'docker compose config' before 'docker stack deploy'."],"tags":["docker-compose","deploy","swarm","replicas","validation","convert"],"backgroundTag":null,"analyzedSha":"4f84911bfe8811e9b028e4b1fee8e7510be79387","analyzedAt":"2026-08-07T12:15:29.814Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}