owasp-amass/amass · error

%s/scope: status=%s

Error message

%s/scope: status=%s

What it means

SessionScope retrieves the asset scope for a session via GET {base}/sessions/{token}/scope/{atype}. When the server responds with a non-200 status and the response body cannot be parsed as a JSON error (readJSONError fails), the client raises this error containing only the session token and HTTP status. It signals the scope request was rejected but the server's failure reason was unavailable/unparseable.

Source

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

		return nil, err
	}
	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
	}

View on GitHub (pinned to 79299dce87)

Solutions

  1. Verify the session token is valid and the session is still active on the server.
  2. Check the base URL points at the engine API server, not a proxy returning HTML error pages.
  3. Confirm the atype passed to SessionScope is a supported oam.AssetType spelled correctly.
  4. Inspect server logs for the corresponding request to learn the real failure reason.
  5. Add error handling that retries after re-establishing the session if the token expired.

Example fix

// before
assets, err := client.SessionScope(ctx, staleToken, oam.Domain)
// after
tok, err := ensureSession(ctx, client) // re-acquire token if expired
if err != nil { return err }
assets, err := client.SessionScope(ctx, tok, oam.Domain)
Defensive patterns

Strategy: try-catch

Validate before calling

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

Type guard

func hasToken(token uuid.UUID) bool { return token != uuid.Nil }

Try / catch

assets, err := client.SessionScope(ctx, token, atype)
if err != nil {
    if strings.Contains(err.Error(), "status=401") || strings.Contains(err.Error(), "status=404") {
        // re-establish session then retry once
    }
    return err
}

Prevention

When it happens

Trigger: Calling Client.SessionScope with a token whose session does not exist or has expired, a wrong oam.AssetType path segment, or when the server returns an error status (404/401/500) with an empty, HTML, or otherwise non-JSON body.

Common situations: Using a stale token after server restart, pointing the client at the wrong base URL (hitting a proxy/HTML error page), or an older server that does not emit the JSON error envelope.

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/3f2bc14a5e976900. Report an issue: GitHub.