What causes "--once must be an ISO 8601 / RFC 3339 timestamp: %w" in pulumi/pulumi?

Use full RFC 3339 format: `--once 2026-09-01T09:00:00Z` (or with explicit offset like +02:00)

--once must be an ISO 8601 / RFC 3339 timestamp: %w

Error message

--once must be an ISO 8601 / RFC 3339 timestamp: %w

What it means

When --once is supplied, its value must parse as an ISO 8601 / RFC 3339 timestamp. If time.Parse(time.RFC3339, once) fails, the command returns this wrapped error indicating the format is invalid.

Source

Thrown at pkg/cmd/esc/cli/env_schedule_edit.go:75

				return errors.New("the edit command does not accept versions")
			}

			scheduleID := args[0]
			if scheduleID == "" {
				return errors.New("schedule ID cannot be empty")
			}

			switch {
			case cron == "" && once == "":
				return errors.New("exactly one of --cron or --once must be set")
			case cron != "" && once != "":
				return errors.New("only one of --cron or --once may be set")
			}

			if once != "" {
				t, err := time.Parse(time.RFC3339, once)
				if err != nil {
					return fmt.Errorf("--once must be an ISO 8601 / RFC 3339 timestamp: %w", err)
				}
				if !t.After(time.Now()) {
					return errors.New("--once must be a timestamp in the future")
				}
			}

			req := client.UpdateEnvironmentScheduleRequest{
				ScheduleCron: cron,
				ScheduleOnce: once,
			}

			s, err := env.esc.client.UpdateEnvironmentSchedule(ctx, ref.orgName, ref.projectName, ref.envName, scheduleID, req)
			if err != nil {
				return err
			}

			fmt.Fprintf(env.esc.stdout, "Updated schedule %s for %s/%s/%s\n",
				s.ID, ref.orgName, ref.projectName, ref.envName)

View on GitHub (pinned to 793f7b2e16)

Solutions

Use full RFC 3339 format: `--once 2026-09-01T09:00:00Z` (or with explicit offset like +02:00)
Generate the timestamp with a tool that emits RFC 3339, e.g. `date -u -d '+1 day' +%Y-%m-%dT%H:%M:%SZ`

Example fix

// before
esc env schedule edit org/proj/env sched-123 --once "2026-09-01 09:00:00"
// after
esc env schedule edit org/proj/env sched-123 --once "2026-09-01T09:00:00Z"

Defensive patterns

Strategy: validation

Validate before calling

date -u -d "$ONCE" +%Y-%m-%dT%H:%M:%SZ >/dev/null 2>&1 || { echo "ONCE must be RFC 3339" >&2; exit 1; }

Prevention

Always generate timestamps with +%Y-%m-%dT%H:%M:%SZ
Use T separator and Z/offset timezone
Test format with `date` before passing to CLI

When it happens

Trigger: Passing --once values like `2026-09-01 09:00:00` (space instead of T), a date without time/zone (`2026-09-01`), or locale-formatted timestamps.

Common situations: Hand-writing timestamps without the required `T` separator or timezone offset; shell date output not matching RFC 3339.

Related errors

AI-assisted analysis of pulumi/pulumi@793f7b2e16 (2026-08-31). Data as JSON: /api/errors/726e67769f69dd76. Report an issue: GitHub.