Postconditions: what we check

• getSignedUrl · presigner-credential-error

  error
  WhenCredential resolution fails: no credentials configured, IAM role unavailable, credentials expired, invalid access key ID, or wrong secret key
  ThrowsCredentialsProviderError when credentials cannot be resolved (no env vars, no IAM role, no credential file). CredentialsError or generic Error on expired/invalid credentials. All errors reject the returned Promise.
  Required handlingCaller MUST wrap getSignedUrl() in try-catch. Credential failures are common in serverless environments where IAM roles may not be configured, env vars may be missing (VERCEL deployment, CI), or tokens may expire. Minimum handling: try { const url = await getSignedUrl(s3Client, command, { expiresIn: 3600 }); return url; } catch (err) { console.error('Failed to generate presigned URL:', err); throw err; }
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1][2]
• getSignedUrl · presigner-expires-in-too-large

  error
  Whenoptions.expiresIn is set to a value greater than 604800 (7 days in seconds). This is a common mistake when developers confuse milliseconds with seconds, pass Date.now() directly, or attempt to create "permanent" links.
  ThrowsPromise.reject() with the string message: "Signature version 4 presigned URLs must have an expiration date less than one week in the future". This is a string rejection (not an Error instance) from @smithy/signature-v4.
  Required handlingCaller MUST wrap getSignedUrl() in try-catch and validate expiresIn is <= 604800. Note: if using temporary credentials (IAM role, STS), the URL will expire earlier than expiresIn — at the point the underlying STS token expires. Safe maximum: const url = await getSignedUrl(s3Client, command, { expiresIn: 3600, // 1 hour — well within the 7-day maximum });
  costlowin prodimmediate exceptionusers seedegraded performancevisibilitysilent
  Sources[3][4]
• getSignedUrl · presigner-not-valid-http-request

  error
  WhenThe resolved request object passed through the client middleware stack is not an HttpRequest instance. This happens when a custom Command implementation builds a non-HTTP payload, when serializers are mis-wired, or when getSignedUrl is called against a non-S3-shaped client whose internal request is something other than HttpRequest. Rare but production-visible when teams roll custom commands for special-case S3 access patterns.
  ThrowsError("Request to be presigned is not an valid HTTP request.") — thrown synchronously inside the async middleware, surfaces as a rejected Promise to the getSignedUrl caller.
  Required handlingWrap getSignedUrl() in try-catch. Distinguish this error from credential errors by message content if you need to alert differently (this signals a wiring/serializer bug, not a runtime credential failure).
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[5]
• getSignedUrl · presigner-invalid-credential-object

  error
  WhenThe AWS credentials object returned by the credential provider is malformed: missing accessKeyId, missing secretAccessKey, or either field is not a string. Common when a custom credential provider returns a partial object, or when environment variables are set to empty strings rather than being absent.
  ThrowsError("Resolved credential object is not valid") from @smithy/signature-v4. This is distinct from CredentialsProviderError — the provider resolved successfully but returned an unusable object.
  Required handlingCaller MUST wrap getSignedUrl() in try-catch. Validate that AWS credentials have both accessKeyId and secretAccessKey before calling. Check for empty string values in addition to undefined.
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[6]
• S3RequestPresigner.presign · presigner-class-presign-expires-error

  error
  Whenoptions.expiresIn exceeds 604800 seconds (7 days). Same limit as getSignedUrl. Since the default is 900s, this only triggers with explicit large values.
  ThrowsPromise.reject() with string "Signature version 4 presigned URLs must have an expiration date less than one week in the future". String rejection, not Error instance.
  Required handlingWrap in try-catch. Ensure expiresIn <= 604800 when passed explicitly.
  costlowin prodimmediate exceptionusers seedegraded performancevisibilitysilent
  Sources[4]
• S3RequestPresigner.presign · presigner-class-presign-sigv4a-missing-crt

  error
  WhenThe S3 bucket uses S3 Multi-Region Access Points (MRAPs) requiring SigV4a signing (signingRegion = '*'). The @aws-sdk/signature-v4-crt or @aws-sdk/signature-v4a package is not installed/registered. This occurs when using MRAPs in serverless environments where native addons are unavailable.
  ThrowsError: "presign with signingRegion '*' is only supported when using the CRT dependency @aws-sdk/signature-v4-crt. Please check whether you have installed the '@aws-sdk/signature-v4-crt' package explicitly."
  Required handlingWrap in try-catch. If using S3 Multi-Region Access Points, install and register @aws-sdk/signature-v4-crt (native module, Node.js only) or @aws-sdk/signature-v4a (pure JS). Cannot be used in browser or edge runtimes without the JS implementation.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[7][8]
• S3RequestPresigner.presign · presigner-class-presign-invalid-credentials

  error
  WhenThe credential object passed to the signer is malformed (missing accessKeyId or secretAccessKey). Same as presigner-invalid-credential-object for getSignedUrl.
  ThrowsError("Resolved credential object is not valid")
  Required handlingWrap in try-catch. Validate credentials object before constructing S3RequestPresigner.
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[6]
• S3RequestPresigner.presignWithCredentials · presigner-presign-with-credentials-mrap-unsupported

  error
  Whenoptions.signingRegion is '*' (required for S3 Multi-Region Access Points). presignWithCredentials explicitly does not support MRAP / SigV4a signing. This is a hard limitation distinct from the CRT availability check — even with CRT installed, this method throws.
  ThrowsError("Method presignWithCredentials is not supported for [signingRegion=*].") Thrown synchronously within the returned Promise.
  Required handlingWrap in try-catch. For MRAP buckets, use S3RequestPresigner.presign() instead, which does support SigV4a via CRT. Do not use presignWithCredentials with MRAPs.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[7][8]
• S3RequestPresigner.presignWithCredentials · presigner-presign-with-credentials-expires-error

  error
  Whenoptions.expiresIn exceeds 604800 seconds (7 days). Same MAX_PRESIGNED_TTL limit applies to all presigning paths including presignWithCredentials.
  ThrowsPromise.reject() with string "Signature version 4 presigned URLs must have an expiration date less than one week in the future".
  Required handlingWrap in try-catch. Validate expiresIn <= 604800.
  costlowin prodimmediate exceptionusers seedegraded performancevisibilitysilent
  Sources[4]

Sources

Every postcondition cites at least one of these. Grouped by source type; numbered to match the footnotes above.

Research notes

Curator notes from SOURCES.md captured when the profile was written so you can verify the reasoning, not just the rules.