What causes "listSessions: status=%s" in owasp-amass/amass?

Run Client.HealthCheck first to verify you are reaching the correct amass API server before interpreting the failure.

listSessions: status=%s

Error message

listSessions: status=%s

What it means

This error is returned by Client.ListSessions when the GET to {base}/api/v1/sessions/list returns a status other than 200 OK and the response body could not be parsed as a JSON error envelope (readJSONError failed). Only the HTTP status string is available because the server replied with a non-JSON body (HTML error page, empty body, plain text). The caller receives no session tokens.

Source

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

	var out CreateSessionResponse
	if err := json.Unmarshal([]byte(resp.Body), &out); err != nil {
		return uuid.UUID{}, err
	}

	return uuid.Parse(out.SessionToken)
}

// Lists the active session and associated tokens on the server.
func (c *Client) ListSessions(ctx context.Context) ([]uuid.UUID, error) {
	resp, err := amasshttp.RequestWebPage(ctx, c.httpClient, &amasshttp.Request{URL: c.base + "/sessions/list"})
	if err != nil {
		return nil, err
	}

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

	var out ListSessionsResponse
	if err := json.Unmarshal([]byte(resp.Body), &out); err != nil {
		return nil, err
	}

	tokens := make([]uuid.UUID, 0, len(out.SessionTokens))
	for _, t := range out.SessionTokens {
		token, err := uuid.Parse(t)
		if err != nil {
			return nil, err
		}
		tokens = append(tokens, token)
	}
	return tokens, nil

View on GitHub (pinned to 79299dce87)

Solutions

Run Client.HealthCheck first to verify you are reaching the correct amass API server before interpreting the failure.
Verify the NewClient URL and that the server exposes /api/v1/sessions/list for the version you compiled against (404 implies path/version mismatch).
If the status is 5xx, check proxy and server logs (nginx, ALB, amass server) for the underlying outage and retry once the service is healthy.
Confirm no auth middleware is intercepting with a plain-text 401/403; supply required credentials or headers.
Upgrade client and server together if the API surface changed.

Example fix

// before: ignoring failure mode
sessions, err := c.ListSessions(ctx)

// after: health-check and distinguish retryable statuses
if !c.HealthCheck(ctx) {
    return fmt.Errorf("amass API unreachable; not calling ListSessions")
}
sessions, err := c.ListSessions(ctx)
if err != nil && strings.Contains(err.Error(), "50") {
    sessions, err = c.ListSessions(ctx) // retry once on 5xx
}

Defensive patterns

Strategy: try-catch

Validate before calling

// Gate ListSessions behind a health/auth probe
if !client.HealthCheck(ctx) {
    return fmt.Errorf("amass API unreachable; skipping ListSessions")
}
resp, err := http.Get(baseURL + "/api/v1/sessions/list")
if err == nil && resp.StatusCode == http.StatusNotFound {
    return fmt.Errorf("server does not expose /api/v1/sessions/list; version mismatch?")
}

Try / catch

sessions, err := client.ListSessions(ctx)
if err != nil {
    if strings.Contains(err.Error(), "listSessions: status=") &&
        !strings.Contains(err.Error(), "error=") {
        // non-JSON body: gateway/HTML page — check infra, retry with backoff
        return retryWithBackoff(func() error {
            sessions, err = client.ListSessions(ctx)
            return err
        })
    }
    return err
}

Prevention

HealthCheck before listing so you fail fast with a clear message instead of a bare status string.
Keep client and server versions aligned; a 404 here usually means the route moved or the server is the wrong version.
Configure proxies to pass JSON error bodies through instead of HTML error pages.
Apply bounded retry with backoff only for 5xx statuses; 4xx statuses need configuration fixes, not retries.
Remember this variant lacks the server's error detail — correlate with server/gateway logs at the same timestamp.

When it happens

Trigger: Calling Client.ListSessions when the server responds non-200 with a non-JSON body: proxy/gateway HTML 502/503/504 pages, 404 HTML page because the path or API version is wrong, empty 500 from a crashed handler, or plain-text 401 from an auth middleware.

Common situations: Wrong base URL or port in NewClient so a proxy or wrong service answers; client/server API version mismatch (no /api/v1/sessions/list route); server down or restarting behind a load balancer; network middleware (ingress controller) intercepting the request.

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/045311bd7e50a620. Report an issue: GitHub.