owasp-amass/amass · error

listSessions: status=%s error=%s

Error message

listSessions: status=%s error=%s

What it means

This error is returned by Client.ListSessions when the amass engine server responds to GET /api/v1/sessions/list with a non-200 status. The error string embeds the HTTP status (e.g. '500 Internal Server Error') and, when the response body is a JSON error object that readJSONError can decode, the server's error message. It is the library's way of surfacing a server-side rejection of the session listing request.

Source

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

		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

  1. Check the HTTP status embedded in the error: 404 usually means the base URL or API path is wrong - verify the URL passed to NewClient points at the engine's /api/v1 root
  2. For 502/503, verify the engine server process is running and reachable (use HealthCheck before ListSessions) and restart it if needed
  3. For 401/403, fix authentication/authorization on the server or the client's credentials
  4. If the message lacks 'error=', capture the raw response body to see what non-JSON payload (HTML proxy page, empty body) the server returned
  5. Retry with backoff for transient 5xx; report persistent 500s to the server operator with server logs

Example fix

// before: calling with the wrong base URL
client, _ := v1.NewClient("https://engine.example.com") // serves UI, not API

// after: point at the API root and health-check first
client, _ := v1.NewClient("https://engine.example.com") // base becomes /api/v1
if !client.HealthCheck(ctx) {
    log.Fatal("engine API unreachable; check server and base URL")
}
tokens, err := client.ListSessions(ctx)
Defensive patterns

Strategy: try-catch

Validate before calling

// Go: gate on health before listing
if !client.HealthCheck(ctx) {
    return fmt.Errorf("engine API unreachable at %s", baseURL)
}

Try / catch

// Go
func listSessionsSafe(ctx context.Context, c *v1.Client) ([]uuid.UUID, bool, error) {
    tokens, err := c.ListSessions(ctx)
    if err == nil {
        return tokens, false, nil
    }
    if s := err.Error(); strings.Contains(s, "502") || strings.Contains(s, "503") || strings.Contains(s, "504") {
        return nil, true, err // retryable
    }
    return nil, false, err
}

Prevention

When it happens

Trigger: Calling ListSessions(ctx) when the server returns any status other than 200 for /api/v1/sessions/list: the API server is down or restarting behind a proxy (502/503), the request hits a wrong base URL that answers with 404, auth/permission middleware rejects the request (401/403), or the server's session store fails (500). The variant with 'error=' only occurs when the body parses as a JSON error; the variant without it occurs when the body is HTML, empty, or non-JSON (e.g. a proxy error page).

Common situations: Pointing the client at a base URL that serves the UI or a different API version instead of the engine API; the engine process crashed and a reverse proxy returns 502; misconfigured auth token so the endpoint returns 403; firewall/ingress returning an HTML error page that readJSONError cannot decode.

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/76b8dee6c3ecbb15. Report an issue: GitHub.