{"record":{"id":"82b2f753d72c7d28","repo":"docker/compose","slug":"service-q-pre-start-d-per-replica-is-not-yet-s","errorCode":null,"errorMessage":"service %q pre_start[%d]: per_replica is not yet supported; remove per_replica or set it to false","messagePattern":"service %q pre_start\\[(.+?)\\]: per_replica is not yet supported; remove per_replica or set it to false","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/compose/pre_start.go","lineNumber":64,"sourceCode":"\t\t}\n\t}\n\treturn pick\n}\n\n// runPreStart executes the service's pre_start hooks sequentially, in declared\n// order. Each hook runs as an ephemeral container that shares the service\n// container's volumes via VolumesFrom and is attached to the same networks.\n// A non-zero exit gates service start.\n//\n// With per_replica: false (the only currently supported mode), the hook sees\n// the volumes of the first non-running replica only — anonymous volumes and\n// tmpfs mounts are per-replica and not shared. Use named volumes or bind\n// mounts for data the hook produces.\nfunc (s *composeService) runPreStart(ctx context.Context, project *types.Project, service types.ServiceConfig, ctr container.Summary, listener api.ContainerEventListener) error {\n\t// Validate every hook up front so an unsupported entry never triggers any I/O.\n\tfor i, hook := range service.PreStart {\n\t\tif hook.PerReplica {\n\t\t\treturn fmt.Errorf(\"service %q pre_start[%d]: per_replica is not yet supported; remove per_replica or set it to false\", service.Name, i)\n\t\t}\n\t}\n\tfor i, hook := range service.PreStart {\n\t\tif err := s.runPreStartHook(ctx, project, service, ctr, i, hook, listener); err != nil {\n\t\t\treturn err\n\t\t}\n\t}\n\treturn nil\n}\n\nfunc (s *composeService) runPreStartHook(\n\tctx context.Context, project *types.Project, service types.ServiceConfig,\n\tctr container.Summary, index int, hook types.ServiceHook, listener api.ContainerEventListener,\n) error {\n\tcreated, err := s.createPreStartContainer(ctx, project, service, ctr, hook)\n\tif err != nil {\n\t\treturn err\n\t}","sourceCodeStart":46,"sourceCodeEnd":82,"githubUrl":"https://github.com/docker/compose/blob/ddc4b044b62e9f715212ea4143fa830fac76382f/pkg/compose/pre_start.go#L46-L82","documentation":"pre_start hooks currently support only the default per-replica:false mode, where one hook container runs against the first non-running replica's volumes. Setting per_replica: true is rejected up front, before any container I/O, so no partial state is created.","triggerScenarios":"A service defines pre_start entries with per_replica: true and docker compose up (or any command materializing the service) runs the runPreStart validation loop.","commonSituations":"Users copying per-replica init patterns from other orchestrators (e.g. init containers per pod); compose files written against a future/experimental schema; docs from a newer compose where the feature landed.","solutions":["Remove per_replica or set it to false in the pre_start entry","Make the hook idempotent so one shared run suffices (use named volumes or binds, not per-replica anonymous volumes)","If per-replica init is a hard requirement, run init logic inside each service container (entrypoint wrapper) instead"],"exampleFix":"# before\nservices:\n  app:\n    pre_start:\n      - command: ./init.sh\n        per_replica: true\n\n# after\nservices:\n  app:\n    pre_start:\n      - command: ./init.sh\n        per_replica: false","handlingStrategy":"validation","validationCode":"for i, h := range service.PreStart {\n    if h.PerReplica {\n        return fmt.Errorf(\"pre_start[%d]: per_replica unsupported on this compose version\", i)\n    }\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Do not use per_replica: true until your compose version documents support","Design pre_start hooks as single shared runs over named volumes/binds"],"tags":["pre-start","hooks","replicas","validation"],"backgroundTag":null,"analyzedSha":"ddc4b044b62e9f715212ea4143fa830fac76382f","analyzedAt":"2026-08-15T13:31:42.319Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}