owasp-amass/amass · error

%s/scope: status=%s error=%s

Error message

%s/scope: status=%s error=%s

What it means

SessionScope's richer variant of the non-200 handling: when the server responds with a non-200 status AND its body parses as a JSON error via readJSONError, the client includes the server-provided message in the error. It reports the session token, HTTP status, and the server's error text for the scope request.

Source

Thrown at engine/api/client/v1/client.go:205

	return &st, nil
}

// Retrieves scope for the session associated with the provided token.
func (c *Client) SessionScope(ctx context.Context, token uuid.UUID, atype oam.AssetType) ([]oam.Asset, error) {
	sessionID := token.String()
	atypestr := strings.ToLower(string(atype))
	u := fmt.Sprintf("%s/sessions/%s/scope/%s", c.base, sessionID, atypestr)
	resp, err := amasshttp.RequestWebPage(ctx, c.httpClient, &amasshttp.Request{URL: u})
	if err != nil {
		return nil, err
	}

	if resp.StatusCode != http.StatusOK {
		msg, err := readJSONError(resp.Body)
		if err != nil {
			return nil, fmt.Errorf("%s/scope: status=%s", token.String(), resp.Status)
		}
		return nil, fmt.Errorf("%s/scope: status=%s error=%s", token.String(), resp.Status, msg)
	}

	reader := strings.NewReader(resp.Body)
	readCloser := io.NopCloser(reader)
	defer func() { _ = readCloser.Close() }()

	return apiclient.DecodeAssetsForScopeEndpoint(atype, readCloser)
}

// Creates a new asset on the server associated with the provided token.
func (c *Client) CreateAsset(ctx context.Context, token uuid.UUID, asset oam.Asset) (string, error) {
	atype := strings.ToLower(string(asset.AssetType()))
	raw, err := asset.JSON()
	if err != nil {
		return "", err
	}

	sessionID := token.String()

View on GitHub (pinned to 79299dce87)

Solutions

  1. Read the error=%s portion: it contains the server's own explanation.
  2. Validate the session token before calling; re-authenticate if it was rejected.
  3. Check that the requested asset type scope exists for this session.
  4. Retry the request if the server reported a transient (5xx) condition.

Example fix

// before
assets, err := client.SessionScope(ctx, token, atype)
log.Println(err) // opaque
// after
assets, err := client.SessionScope(ctx, token, atype)
if err != nil {
    var he *HTTPStatusError // or strings.Contains check on "status=401"
    if errors.As(err, &he) && he.StatusCode == 401 { token = reauth(ctx) }
    return err
}
Defensive patterns

Strategy: try-catch

Validate before calling

if token == uuid.Nil { return errors.New("session token not initialized") }

Type guard

func isAuthFailure(err error) bool { return err != nil && strings.Contains(err.Error(), "status=401") }

Try / catch

assets, err := client.SessionScope(ctx, token, atype)
if err != nil {
    var srvMsg string
    if m := serverErrorText(err); m != "" { srvMsg = m } // parse error=... suffix
    log.Printf("scope lookup failed: %v (%s)", err, srvMsg)
    return err
}

Prevention

When it happens

Trigger: Calling Client.SessionScope when the server explicitly rejects the request — e.g. invalid session token (401), unknown session or asset type (404), or internal failure (500) — and returns a JSON error body.

Common situations: Expired or revoked session tokens, requesting a scope for an asset type the session never queried, or server-side validation failures during bulk data collection.

Understand the failure class

Background: "API error: {status}" and "HTTP 401/403/404/429/5xx" errors: non-2xx HTTP responses explained — this error's family across 27 libraries.

Related errors

AI-assisted analysis of owasp-amass/amass@79299dce87 (2026-09-06). Data as JSON: /api/errors/0e7071f75a0b2ee8. Report an issue: GitHub.