Exit codes

Every command ends with one of these codes. Scripts and CI jobs can branch on them.

Code	Meaning	Typical cause
0	Success.	The files were written (or the policy printed, or the server stopped normally). --version and --help also return 0.
1	Unexpected failure.	An AWS API error that is not about credentials (throttling that exhausted its retries, a service error); a file that cannot be read or written (permission denied on the output directory, disk full); a --cache or --account-names file that is not valid JSON or has the wrong shape; an invalid VPCATLAS_* value for serve; the policy file missing from the installation (iam-policy).
2	Bad usage.	Set by the command line parser before anything runs: an unknown option, a bad value, a --cache or --account-names file that does not exist, an unknown --format or --level, a region that is not a region name, --mfa-serial without --mfa-token (or the reverse), several --profile together with --role-arn, a --session-duration outside 900 to 43200, a --role-session-name that is not 2 to 64 characters from letters, digits and + = , . @ _ -, a --concurrency outside 1 to 32, a --port outside 1 to 65535.
3	AWS credentials or access problem.	No credentials found; the profile does not exist; the token expired (ExpiredToken) or was rejected (InvalidClientTokenId, UnrecognizedClientException, SignatureDoesNotMatch, AuthFailure); AccessDenied when assuming the role, often a wrong ARN, a wrong --external-id or a trust policy that does not name the caller.
4	Discovery finished with issues while --strict is set.	A call was denied or failed in some region or service and the scan recorded it. The files are written before the exit, and the summary lists the first ten issues. Without --strict the same run exits 0.

Notes:

• Runtime errors print one line on standard error: error: <message>; usage errors print the parser's message with the option that failed. For a failure with code 1 that comes from a value, run again with -vv to see the details in the log.
• Code 4 only exists for discover, inventory and diagram. serve never returns 3 or 4: a failed scan is shown by the dashboard and the process keeps running.
• An access denied on one API of one service during the scan is not an error by itself: it is recorded as an issue and the scan continues. It only becomes exit code 4 with --strict. An AccessDenied on the credentials themselves (for example in sts:AssumeRole) stops the run with code 3.
• The same codes are listed in vpcatlas --help.