What causes "API key is not defined" in sundowndev/phoneinfoga?

Export NUMVERIFY_API_KEY= before running the scan

API key is not defined

Error message

API key is not defined

What it means

This sentinel error is thrown by numverifyScanner.DryRun during pre-flight validation when the NUMVERIFY_API_KEY environment variable is unset or empty. It is a generic guard, not an API failure: the scanner stops before making any request because the Numverify API requires a valid API key for authentication. The input at fault is the missing environment variable; setting NUMVERIFY_API_KEY (e.g. via ScannerOptions env) resolves it.

Source

Thrown at lib/remote/numverify_scanner.go:44

}

func NewNumverifyScanner(s suppliers.NumverifySupplierInterface) Scanner {
	return &numverifyScanner{client: s}
}

func (s *numverifyScanner) Name() string {
	return Numverify
}

func (s *numverifyScanner) Description() string {
	return "Request info about a given phone number through the Numverify API."
}

func (s *numverifyScanner) DryRun(_ number.Number, opts ScannerOptions) error {
	if opts.GetStringEnv("NUMVERIFY_API_KEY") != "" {
		return nil
	}
	return errors.New("API key is not defined")
}

func (s *numverifyScanner) Run(n number.Number, opts ScannerOptions) (interface{}, error) {
	apiKey := opts.GetStringEnv("NUMVERIFY_API_KEY")

	res, err := s.client.Request().SetApiKey(apiKey).ValidateNumber(n.International)
	if err != nil {
		return nil, err
	}

	data := NumverifyScannerResponse{
		Valid:               res.Valid,
		Number:              res.Number,
		LocalFormat:         res.LocalFormat,
		InternationalFormat: res.InternationalFormat,
		CountryPrefix:       res.CountryPrefix,
		CountryCode:         res.CountryCode,
		CountryName:         res.CountryName,

View on GitHub (pinned to 55807b05b7)

Solutions

Export NUMVERIFY_API_KEY=<your key> before running the scan
Ensure your .env/secrets file is actually loaded in the environment where the tool runs (CI secret, docker --env-file, etc.)
Verify with `echo $NUMVERIFY_API_KEY` that it is non-empty
Disable the numverify scanner if you do not intend to use it

Example fix

// before
scan --number +14155552671   # NUMVERIFY_API_KEY empty
// after
export NUMVERIFY_API_KEY=abc123def456
scan --number +14155552671

Defensive patterns

Strategy: validation

Validate before calling

if os.Getenv("NUMVERIFY_API_KEY") == "" {
    return errors.New("numverify scanner requires NUMVERIFY_API_KEY")
}

Prevention

Export NUMVERIFY_API_KEY in your shell profile or CI secrets
Verify key validity in the numverify dashboard before scans
Run DryRun-based smoke tests as part of setup
Standardize credential loading (one .env sourced everywhere)

When it happens

Trigger: Running a scan with the numverify scanner enabled while the NUMVERIFY_API_KEY environment variable is unset or empty string.

Common situations: Signed up for numverify but never exported the key, running in CI where secrets were not injected, restarting a shell without re-sourcing the env file, or misspelling the variable name.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

AI-assisted analysis of sundowndev/phoneinfoga@55807b05b7 (2026-09-03). Data as JSON: /api/errors/4acc7165b3927c93. Report an issue: GitHub.