Why Are Previews Not Rendering for Certain File Types (e.g. .txt, .png) in Quilt?

🐞 Why Are Previews Not Rendering for Certain File Types (e.g. .txt, .png) in Quilt?

Experiencing missing or broken previews in Quilt for certain file types like plain text or PNG images? This issue often stems from networking misconfigurations, missing permissions, or Lambda function failures. Here’s how to investigate and fix it.

❓ Question

When attempting to preview certain files (e.g., .txt, .png) through Quilt, the UI fails to render them correctly — previews may appear as a blank area, a spinner, or a failed request in the browser dev tools. What could be causing this?

✅ Answer

This problem typically arises when the API Gateway or Lambda functions involved in generating previews are inaccessible or misconfigured. This can happen due to:

• Missing inbound HTTPS permissions on the API Gateway
• A VPC setup that blocks outbound internet access
• Lambda runtime errors not surfaced to the UI

🔍 Root Causes

🔐 1. API Gateway Security Group Doesn’t Allow HTTPS

If your API Gateway is deployed in a VPC, it may be attached to a security group that doesn’t allow inbound traffic on port 443. As a result, preview requests from the browser are dropped.

🌐 2. API Gateway Lacks Internet Egress

API Gateways deployed inside a private subnet may not have outbound internet access if:

• There's no NAT Gateway for the subnet
• Route tables don't direct traffic to the internet

🪵 3. Lambda Function Fails Silently

The Lambda function responsible for processing previews may:

• Lack permissions (e.g., to read from S3 or return binary media types)
• Encounter runtime errors (e.g., for unsupported file types)
• Fail without surfacing errors in the UI

🛠️ How to Fix It

🔧 Step 1: Validate API Gateway Security Group

1. Open the VPC dashboard in the AWS Console.
2. Go to Security Groups, and locate the one attached to your API Gateway’s network interface.
3. Ensure the following rule exists:

Type: HTTPS
Protocol: TCP
Port Range: 443
Source: 0.0.0.0/0

🛑 Without this rule, browser requests to the preview endpoint will never reach your backend.

🌐 Step 2: Review VPC and Routing Configuration

1. Check if your API Gateway is deployed within a VPC.
2. Identify whether it resides in private or public subnets.
3. Ensure either of the following:
   • The subnet is public with a route to an internet gateway
   • The subnet is private, but has:
     • a NAT Gateway in a public subnet
     • a route for 0.0.0.0/0 to the NAT

📜 Step 3: Inspect Lambda Function Logs in CloudWatch

1. Go to CloudWatch > Log Groups.
2. Locate the group for the preview-related Lambda function.
3. Open the most recent log streams and look for:
   • AccessDeniedException
   • TimeoutError or SocketError
   • Unsupported file format or MIME errors

{
  "errorType": "AccessDeniedException",
  "errorMessage": "User is not authorized to access S3 object: preview/file.txt",
  "stackTrace": [...]
}

💡 Ensure the Lambda's IAM role has s3:GetObject permissions for the relevant bucket/prefix.

🧪 Optional Diagnostic Tips

• Use browser Dev Tools > Network tab to inspect the preview request
• Try direct curl calls to the API Gateway preview endpoint
• Add structured logging in the Lambda to capture file type, render duration, and fetch status

📞 Still Having Issues?

Contact the Quilt Support Team with the following:

• Affected file types and names
• CloudWatch logs showing Lambda errors
• Details about API Gateway, VPC, and subnet configuration