owasp-amass/amass · error

createSession: status=%s error=%s

Error message

createSession: status=%s error=%s

What it means

This error is returned by Client.CreateSession when the POST to {base}/api/v1/sessions returns a non-201 status and readJSONError successfully extracted the server's error message from the JSON body. It carries the HTTP status plus the server-provided error detail, making it the informative variant of the createSession failure. The embedded message is what the server chose to report (e.g. invalid configuration, duplicate session, unauthorized).

Source

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

		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
	}

	if resp.StatusCode != http.StatusOK {

View on GitHub (pinned to 79299dce87)

Solutions

  1. Read the error=%s portion of the message — it contains the server's own explanation — and address that specific cause first.
  2. Log the full request payload (the marshaled config) and compare against the API contract for the server version you are running.
  3. Check authentication: if status is 401/403, supply or refresh credentials expected by the server deployment.
  4. Update the client library and server to matching versions if the config schema changed between releases.
  5. Retry after fixing server-side issues if the status is 5xx and the message indicates a transient backend failure.

Example fix

// before: ignoring the server-provided detail
if err != nil {
    return err
}

// after: branch on the status and surface the server message
if err != nil {
    var httpErr *clientv1.StatusError
    if errors.As(err, &httpErr) && strings.HasPrefix(httpErr.Status, "5") {
        return retryable(fmt.Errorf("createSession: %w", err))
    }
    return fmt.Errorf("session rejected by server: %w", err)
}
Defensive patterns

Strategy: try-catch

Validate before calling

// Validate the config before sending it to the server
raw, err := json.Marshal(cfg)
if err != nil { return err }
if len(raw) == 0 || !json.Valid(raw) {
    return fmt.Errorf("config does not serialize to valid JSON")
}
// Ensure server health/auth before submitting
if !client.HealthCheck(ctx) {
    return fmt.Errorf("amass API server unhealthy; fix server/auth before CreateSession")
}

Try / catch

tok, err := client.CreateSession(ctx, cfg)
if err != nil {
    msg := err.Error()
    if i := strings.Index(msg, "error="); i >= 0 {
        serverMsg := msg[i+len("error="):]
        log.Printf("server rejected session creation: %s", serverMsg)
        // branch on serverMsg to fix config/auth accordingly
    }
    if strings.Contains(msg, "401") || strings.Contains(msg, "403") {
        return refreshCredentialsAndRetry()
    }
    return err
}

Prevention

When it happens

Trigger: Calling Client.CreateSession when the server rejects the session creation and returns a structured JSON error: invalid or unsupported Config fields in the POST body, authentication/authorization failure (401/403), request validation failure (400), or server-side failure (500) that the API reports as a JSON error envelope.

Common situations: Submitting a Config the server version does not accept (schema drift between client and server); expired or missing credentials on an authenticated deployment; malformed or nil-adjacent config values failing server-side validation; server storage/DB errors surfaced as 500 with a JSON message.

Related errors

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