What causes "not found" in owasp-amass/amass?

Verify the session token/scope identifier via ListSessions before calling.

owasp-amass/amass · error · ErrNotFound

not found

Error message

not found

What it means

ErrNotFound is the package-level sentinel for HTTP 404 responses in the v1 API handlers. Handlers return it (via writeError with http.StatusNotFound) when the requested resource — sessions list, session by token, stats, scope, or asset ingest targets — does not exist.

Source

Thrown at engine/api/server/v1/handlers.go:62

type AddAssetResponse struct {
	EntityID string `json:"entityID"`
}

// Bulk typed add: {"items":[ <OAM obj>, <OAM obj>, ... ]}
// where each item is arbitrary JSON object without "type".
type BulkAddAssetsRequest struct {
	Items []json.RawMessage `json:"items"`
}

type BulkAddAssetsResponse struct {
	Ingested int64 `json:"ingested"`
	Stored   int64 `json:"stored"`
	Failed   int64 `json:"failed"`
}

var (
	ErrNotFound   = errors.New("not found")
	ErrBadRequest = errors.New("bad request")
)

type V1Handlers struct {
	ctx context.Context
	log *slog.Logger
	dis et.Dispatcher
	mgr et.SessionManager
}

func NewV1Handlers(ctx context.Context, dis et.Dispatcher, mgr et.SessionManager, log *slog.Logger) (*V1Handlers, error) {
	return &V1Handlers{
		ctx: ctx,
		log: log,
		dis: dis,
		mgr: mgr,
	}, nil
}

View on GitHub (pinned to 79299dce87)

Solutions

Verify the session token/scope identifier via ListSessions before calling.
Create/ingest a session before querying or terminating it.
Check the API base URL and path for typos.
Handle HTTP 404 in the client and surface a user-friendly 'resource not found' message.

Example fix

// before
sess := v.mgr.GetSession(token) // nil -> 404
writeError(w, http.StatusNotFound, "session not found", ErrNotFound)
// after
sess := v.mgr.GetSession(token)
if sess == nil {
    return fmt.Errorf("session %q does not exist; call ListSessions first", token)
}

Defensive patterns

Strategy: try-catch

Validate before calling

sessions := client.ListSessions(ctx)
if len(sessions) == 0 { return errors.New("no sessions available") }
// verify token exists before targeting it
found := false
for _, s := range sessions { if s.Token == token { found = true } }
if !found { return fmt.Errorf("session %s not found", token) }

Try / catch

resp, err := client.Do(req)
if err != nil { return err }
if resp.StatusCode == http.StatusNotFound {
    return fmt.Errorf("resource does not exist: %s", req.URL)
}

Prevention

List resources before referencing a specific token/scope.
Validate session tokens are still live (refresh/reconnect).
Use stable identifiers and keep them out of logs that get truncated.
Handle 404 distinctly from other errors in API clients.

When it happens

Trigger: Any v1 handler (ListSessions, TerminateSession, GetStats, GetScope, AddAssetTyped, AddAssetsBulk) finding no matching resource: mgr.GetSessions() is empty, mgr.GetSession(token) returns nil, or the referenced scope/session is missing.

Common situations: Calling the API with an expired or mistyped session token, querying before any sessions are created, or asking for a scope that was deleted or never registered.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

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