spf13/cobra · error

invalid SOURCE_DATE_EPOCH: %v

Error message

invalid SOURCE_DATE_EPOCH: %v

What it means

Returned by fillHeader (used by GenMan / man-page generation) when the SOURCE_DATE_EPOCH environment variable is set but cannot be parsed as a base-10 64-bit integer. SOURCE_DATE_EPOCH is the reproducible-builds convention for pinning the date embedded in generated man pages; cobra honours it only when header.Date is nil (i.e. the caller did not supply a date).

Source

Thrown at doc/man_docs.go:130

	b := genMan(cmd, header)
	_, err := w.Write(md2man.Render(b))
	return err
}

func fillHeader(header *GenManHeader, name string, disableAutoGen bool) error {
	if header.Title == "" {
		header.Title = strings.ToUpper(strings.ReplaceAll(name, " ", "\\-"))
	}
	if header.Section == "" {
		header.Section = "1"
	}
	if header.Date == nil {
		now := time.Now()
		if epoch := os.Getenv("SOURCE_DATE_EPOCH"); epoch != "" {
			unixEpoch, err := strconv.ParseInt(epoch, 10, 64)
			if err != nil {
				return fmt.Errorf("invalid SOURCE_DATE_EPOCH: %v", err)
			}
			now = time.Unix(unixEpoch, 0)
		}
		header.Date = &now
	}
	header.date = header.Date.Format("Jan 2006")
	if header.Source == "" && !disableAutoGen {
		header.Source = "Auto generated by spf13/cobra"
	}
	return nil
}

func manPreamble(buf io.StringWriter, header *GenManHeader, cmd *cobra.Command, dashedName string) {
	description := cmd.Long
	if len(description) == 0 {
		description = cmd.Short
	}

View on GitHub (pinned to adbc881390)

Solutions

  1. Set SOURCE_DATE_EPOCH to a valid Unix epoch integer (seconds since 1970-01-01), e.g. `git log -1 --format=%ct`.
  2. Unset the variable if reproducible dates aren't needed; cobra will then use time.Now().
  3. Alternatively, pass a non-nil header.Date to GenMan so the env-var path is skipped entirely.
  4. Validate the value in your build script before invoking doc generation.

Example fix

# before
export SOURCE_DATE_EPOCH="2024-01-01"
# -> invalid SOURCE_DATE_EPOCH: ...

# after
export SOURCE_DATE_EPOCH=$(git log -1 --format=%ct)
Defensive patterns

Strategy: validation

Validate before calling

// Validate SOURCE_DATE_EPOCH before generating man pages
func checkedEpoch() (int64, error) {
    v := os.Getenv("SOURCE_DATE_EPOCH")
    if v == "" { return 0, nil }
    n, err := strconv.ParseInt(v, 10, 64)
    if err != nil {
        return 0, fmt.Errorf("SOURCE_DATE_EPOCH must be a Unix timestamp; got %q", v)
    }
    return n, nil
}

Type guard

null

Try / catch

if err := doc.GenManTree(cmd, header, dir); err != nil {
    if strings.Contains(err.Error(), "SOURCE_DATE_EPOCH") {
        os.Unsetenv("SOURCE_DATE_EPOCH"); err = doc.GenManTree(cmd, header, dir)
    }
}

Prevention

When it happens

Trigger: Exporting SOURCE_DATE_EPOCH with a non-numeric, negative, empty-after-export, or overflow value, then calling doc.GenManTree / GenMan. strconv.ParseInt(epoch, 10, 64) fails on anything but an optional-signed decimal integer in int64 range.

Common situations: CI/build environments setting SOURCE_DATE_EPOCH from a git timestamp that is empty or formatted (e.g. with a timezone), a stray unit suffix, or a value copied from a different reproducible-builds tool with incompatible formatting.

Related errors

AI-assisted analysis of spf13/cobra@adbc881390 (2026-08-04). Data as JSON: /data/errors/11135b58b13f5912.json. Report an issue: GitHub.