the Amass engine did not respond within the timeout period

Error message

the Amass engine did not respond within the timeout period

What it means

waitForEngineResponse polls engineIsRunning() on a 1-second tick for 60 iterations (60 seconds). If the Amass engine process never becomes responsive within that window, it returns this timeout error and main aborts startup.

Solutions

Check engine logs/startup errors — startEngine discards cmd.Stdout/Stderr, so temporarily capture them to see why the engine never starts.
Verify engineIsRunning's endpoint (port/socket) is reachable and not blocked by firewall or occupied by another process.
Increase the 60-iteration timeout if the machine is slow, and confirm the engine binary launches correctly (run it manually).

Defensive patterns

Strategy: retry

Validate before calling

// before waiting, confirm the engine can start:
cmd := exec.Command(enginePath, "--version")
if err := cmd.Run(); err != nil {
    return fmt.Errorf("engine binary not runnable: %w", err)
}

Try / catch

if err := waitForEngineResponse(); err != nil {
    // capture engine stdout/stderr logs, check port availability, then retry once
    log.Fatalf("engine startup failed: %v", err)
}

Prevention

Don't send engine stdout/stderr to io.Discard — capture to a log file.
Pre-check that the engine's listen port/socket is free.
Ensure any backing services (graph DB) are up before starting the engine.

When it happens

Trigger: Starting the amass engine and it fails to bind/respond to its health/IPC endpoint within 60 seconds — engine binary crashes on launch, port conflict, or slow startup under load.

Common situations: Engine crashing silently because stdout/stderr are discarded (io.Discard) so startup errors are invisible; firewall or missing graph service (e.g. Neo4j/DB) delaying readiness; running in resource-starved containers.

Understand the failure class

Background: Request timed out: what client-side request timeouts mean across libraries (Request timed out, TIMED_OUT, APITimeoutError) — this error's family across 39 libraries.

Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

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

Appendix: source

Thrown at cmd/amass/main.go:183

		viz.CLIWorkflow(cmdName, os.Args[2:])
	default:
		usage()
		_, _ = afmt.R.Fprintf(color.Error, "subcommand provided but not defined: %s\n", os.Args[1])
		os.Exit(1)
	}
}

func waitForEngineResponse() error {
	t := time.NewTicker(time.Second)
	defer t.Stop()

	for range 60 {
		<-t.C
		if engineIsRunning() {
			return nil
		}
	}
	return fmt.Errorf("the Amass engine did not respond within the timeout period")
}

View on GitHub (pinned to 79299dce87)