owasp-amass/amass · error

createSession: status=%s

Error message

createSession: status=%s

What it means

This error is returned by Client.CreateSession when the POST to {base}/api/v1/sessions returns an HTTP status other than 201 Created AND the response body could not be parsed as a JSON error envelope (readJSONError failed). The caller only gets the HTTP status string, with no server-supplied error detail, because the server responded with a non-JSON body (e.g. an HTML error page, empty body, or plain text).

Source

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

	raw, err := json.Marshal(config)
	if err != nil {
		return uuid.UUID{}, err
	}

	resp, err := amasshttp.RequestWebPage(ctx, c.httpClient, &amasshttp.Request{
		Method: http.MethodPost,
		Body:   string(raw),
		URL:    c.base + "/sessions",
		Header: amasshttp.Header{"Content-Type": []string{"application/json"}},
	})
	if err != nil {
		return uuid.UUID{}, err
	}

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

	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
	}

View on GitHub (pinned to 79299dce87)

Solutions

  1. Check what the server actually returned: hit {base}/api/v1/health with Client.HealthCheck first to confirm you are talking to the right service.
  2. Verify the NewClient base URL, port, and that the server is the expected amass API version (v1) — a 404 usually means wrong path or wrong server.
  3. Inspect reverse-proxy/gateway logs if the status is 502/503/504; fix upstream connectivity or wait for the service to recover.
  4. Check server-side logs at the time of the request to find the real error, since the body was not parseable JSON.
  5. Update client and server to matching versions if the API surface changed; re-run the request.

Example fix

// before: calling CreateSession blindly against an unverified endpoint
c, _ := clientv1.NewClient("http://localhost:4000")
tok, err := c.CreateSession(ctx, cfg)

// after: health-check and require JSON-capable server first
c, _ := clientv1.NewClient("http://localhost:4000")
if !c.HealthCheck(ctx) {
    return fmt.Errorf("amass API server unreachable at %s", "http://localhost:4000")
}
tok, err := c.CreateSession(ctx, cfg)
Defensive patterns

Strategy: try-catch

Validate before calling

// Before CreateSession, verify the endpoint is the amass v1 API
if !client.HealthCheck(ctx) {
    return fmt.Errorf("amass API server not reachable/healthy at configured URL")
}
// Optionally probe the route
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 endpoints")
}

Try / catch

tok, err := client.CreateSession(ctx, cfg)
if err != nil {
    var opErr *net.OpError
    if errors.As(err, &opErr) {
        return fmt.Errorf("network/server problem reaching API: %w", err)
    }
    if strings.Contains(err.Error(), "createSession: status=") &&
        !strings.Contains(err.Error(), "error=") {
        // non-JSON body: likely proxy/gateway page — log status and retry or fail fast
        return fmt.Errorf("server returned non-JSON error body: %w", err)
    }
    return err
}

Prevention

When it happens

Trigger: Calling Client.CreateSession when the amass server returns a non-201 status with a non-JSON body: server routing changed (wrong API version/path), a reverse proxy or gateway returns an HTML 502/504 error page, the server crashes and returns an empty 500 body, or authentication middleware returns a plain-text 401/403.

Common situations: Pointing NewClient at the wrong URL or port so a different service (or a proxy) answers; server version mismatch where /api/v1/sessions no longer exists (404 with HTML 404 page); infrastructure errors (502/503/504 from nginx/ALB); server not fully started or DB backend down causing a raw 500 without JSON.

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