goharbor/harbor · error

missing parameter of scan job

Error message

missing parameter of scan job

What it means

Returned by scan Job.Validate when the job parameters map is nil. Scan jobs require at least the registration UUID, the scan request (artifact digest), and mime types; a nil map is rejected before any field extraction is attempted.

Source

Thrown at src/pkg/scan/job.go:112

func (j *Job) MaxFails() uint {
	return 1
}

// MaxCurrency is implementation of same method in Interface.
func (j *Job) MaxCurrency() uint {
	return 0
}

// ShouldRetry indicates if the job should be retried
func (j *Job) ShouldRetry() bool {
	return false
}

// Validate the parameters of this job
func (j *Job) Validate(params job.Parameters) error {
	if params == nil {
		// Params are required
		return errors.New("missing parameter of scan job")
	}

	if _, err := extractRegistration(params); err != nil {
		return errors.Wrap(err, "job validate")
	}

	if _, err := ExtractScanReq(params); err != nil {
		return errors.Wrap(err, "job validate")
	}

	if _, err := extractMimeTypes(params); err != nil {
		return errors.Wrap(err, "job validate")
	}

	if _, err := extractRobotAccount(params); err != nil {
		return errors.Wrap(err, "job validate")
	}

View on GitHub (pinned to 7b2fd08cc5)

Solutions

1. Always pass a non-nil job.Parameters containing registration_uuid, the scan request JSON, and mime_types
2. Validate at the API boundary before enqueuing so users get a 400 instead of a failed job
3. Inspect the failed job's parameters in the jobservice UI to confirm what was attached

Example fix

// before
job := &Job{}
err := job.Validate(nil)

// after
params := job.Parameters{
    JobParamRegistration: reg.UUID,
    JobParameterRequest:  reqJSON,
    JobParameterMimes:    []string{v1.MimeTypeNativeReport},
}
err := job.Validate(params)

if params == nil {
    return errors.New("scan job requires parameters")
}
if err := job.Validate(params); err != nil {
    return err
}

func hasScanParams(p job.Parameters) bool {
    return p != nil && p[JobParamRegistration] != nil && p[JobParameterRequest] != nil
}

When it happens

Trigger: Enqueuing a scan job through the jobservice without parameters; API code building job.Job but never setting params; job re-submission after serialization loss of the parameters blob.

Common situations: Custom integrations invoking the scan job directly; upgrade migrations dropping old job params; on-demand scan endpoints failing to assemble parameters when the request context is incomplete.

Related errors

• File {} not exist
• Internal dir for tls {} not exist
• Port number in metrics is not valid
• Jaeger Colector Endpoint or Agent host not set, must set one
• Jaeger Colector Endpoint and Agent host both set, only can s

AI-assisted analysis of goharbor/harbor@7b2fd08cc5 (2026-08-16). Data as JSON: /api/errors/c689346bcf8d1719. Report an issue: GitHub.